org.eclipse.smila.search.api.helper

Class QueryBuilder

java.lang.Object

org.eclipse.smila.search.api.helper.QueryBuilder

Direct Known Subclasses:

SolrQueryBuilder

public class QueryBuilder
extends java.lang.Object

Builder for Query objects to send to a search service. Most methods just return the QueryBuilder they were called on to make it easy to chain several methods call in a single code line.

Author:

jschumacher

Constructor Summary

Constructors

Constructor and Description
QueryBuilder(java.lang.String workflowName) init request for given pipeline with default data factory.
QueryBuilder(java.lang.String workflowName, DataFactory factory) create for non-default data factory.
QueryBuilder(java.lang.String workflowName, Record request) create based on existing record.

Method Summary

Methods

Modifier and Type	Method and Description
QueryBuilder	addAllOfFilter(java.lang.String attribute, java.lang.Object... values) add a "allOf" filter of required values for an attribute.
QueryBuilder	addAtLeastFilter(java.lang.String attribute, java.lang.Object value) add a "atLeast" filter for the minimum (inclusive lower bound) value of an attribute.
QueryBuilder	addAtMostFilter(java.lang.String attribute, java.lang.Object value) add a "atMost" filter for the maximum (inclusive upper bound) value of an attribute.
QueryBuilder	addAttributeConfig(java.lang.String parameterName, java.lang.String attributeName, AnyMap config) add a complex parameter (ie. the given config) for an attribute: the parameter will be a sequence of maps, each containing the attribute name under key "attribute". e.g.
QueryBuilder	addBoundFilter(java.lang.String attribute, java.lang.String filterType, java.lang.Object boundValue) add a filter with a single value bound.
QueryBuilder	addFacetByAttribute(java.lang.String attribute, int maxCount) add facetby config for attribute with maxcount.
QueryBuilder	addFacetByAttribute(java.lang.String attribute, int maxCount, java.lang.String sortCriterion, QueryConstants.SortOrder sortOrder) add facetby config for attribute with maxcount and sort config for facets.
QueryBuilder	addFacetByConfig(java.lang.String attribute, AnyMap config)
QueryBuilder	addFilter(java.lang.String attribute, AnyMap filter) add a arbitrary complex filter object for an attribute.
QueryBuilder	addGreaterThanFilter(java.lang.String attribute, java.lang.Object value) add a "greaterThan" filter for the exclusive lower bound value of an attribute.
QueryBuilder	addGroupByAttribute(java.lang.String groupCommand, java.lang.String attribute, int maxcount) Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupCommand.
QueryBuilder	addGroupByAttribute(java.lang.String groupName, java.lang.String groupCommand, java.lang.String attribute, int maxcount) Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupName/groupCommand.
QueryBuilder	addGroupByAttribute(java.lang.String groupName, java.lang.String groupCommand, java.lang.String attribute, int maxcount, java.lang.String asMainResult) Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupName/groupCommand and set asMainResult within RecordMetadata/groupby.
QueryBuilder	addGroupByConfig(java.lang.String groupCommand, AnyMap config) Add a group configuration to RecordMetadata/groupby/groupCommand.
QueryBuilder	addGroupByConfig(java.lang.String groupName, java.lang.String groupCommand, AnyMap config) Add a group configuration to RecordMetadata/groupby/groupName/groupCommand.
QueryBuilder	addGroupByConfig(java.lang.String groupName, java.lang.String groupCommand, AnyMap config, java.lang.String asMainResult) Add a group configuration to RecordMetadata/groupby/groupName/groupCommand and set asMainResult within RecordMetadata/groupby.
QueryBuilder	addHighlightByAttribute(java.lang.String... attributes) Add a configuration for each attribute to highlight AnySeq.
QueryBuilder	addHighlightByConfig(java.lang.String attribute, AnyMap config) Add the given configuration for the given attribute to highlight AnySeq.
QueryBuilder	addLessThanFilter(java.lang.String attribute, java.lang.Object value) add a "lessThan" filter for the exclusive upper bound value of an attribute.
QueryBuilder	addListFilter(java.lang.String attribute, java.lang.String filterType, java.lang.Object... values) add a filter with a value list.
QueryBuilder	addNoneOfFilter(java.lang.String attribute, java.lang.Object... values) add a "noneOf" filter of forbidden values for an attribute.
QueryBuilder	addOneOfFilter(java.lang.String attribute, java.lang.Object... values) add a "oneOf" filter of allowed values for an attribute.
QueryBuilder	addParameter(java.lang.String name, java.lang.String value) adds to a parameter sequence.
QueryBuilder	addRangeFilter(java.lang.String attribute, java.lang.Object lowerBound, java.lang.Object upperBound) add range filter (inclusive). bounds may be null.
QueryBuilder	addResultAttributes(java.lang.String... fieldNames) adds the given fieldNames as result field(s).
QueryBuilder	addSortBy(java.lang.String attribute, QueryConstants.SortOrder mode) add an sortby specification.
ResultAccessor	executeRequest(SearchService searchService) execute query on given search service and wrap result in high level result helper.
org.w3c.dom.Document	executeRequestXml(SearchService searchService) execute query on given search service and return search result as XML DOM document.
java.lang.String	executeRequestXmlString(SearchService searchService) execute query on given search service and return search result as XML string.
DataFactory	getFactory()
AnyMap	getMetadata() access underlying query record metadata for advanced manipulation.
Record	getQuery() access underlying query record for advanced manipulation.
java.lang.String	getWorkflowName() the name of the search pipeline to use.
QueryBuilder	setAttachment(java.lang.String name, byte[] attachment) add attachment to query.
QueryBuilder	setId(java.lang.String id) set the ID of the query record.
QueryBuilder	setIndexName(java.lang.String indexName) set the index name for the query.
QueryBuilder	setLanguage(java.lang.String language) set the language parameter for the query.
QueryBuilder	setMaxCount(int maxCount) set the maximum search result size for the query.
QueryBuilder	setOffset(int offset) set the search result offset for the query, i.e. the number of most relevant result objects to skip in the result list.
QueryBuilder	setParameter(java.lang.String name, java.lang.String value) sets a single parameter value.
QueryBuilder	setQuery(java.lang.String queryString) set the textual query string for the query.
QueryBuilder	setQueryAttribute(java.lang.String attributeName, java.lang.Object... values) set attribute in "queryAttribute" part of request.
QueryBuilder	setRanking(Any ranking)
QueryBuilder	setResultAttributes(java.lang.String... attributes) set names attributes to appear in result records.
QueryBuilder	setThreshold(double threshold) set the threshold for the relevance value of search results, i.e. only results having a relevance of at least the threshold value, should be returned to the client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QueryBuilder

public QueryBuilder(java.lang.String workflowName)

init request for given pipeline with default data factory.

Parameters:

workflowName - workflow name.

QueryBuilder

public QueryBuilder(java.lang.String workflowName,
            DataFactory factory)

create for non-default data factory.

Parameters:

workflowName - workflow name.

factory - data factory

QueryBuilder

public QueryBuilder(java.lang.String workflowName,
            Record request)

create based on existing record.

Parameters:

workflowName - workflow name.

request - base request.

Method Detail

setId

public QueryBuilder setId(java.lang.String id)

set the ID of the query record. If the ID is not set by the client, the builder will create an Id just before the request is executed, using the local IP address as source and a random UUID as key.

Parameters:

id - Id

Returns:

"this"

setQuery

public QueryBuilder setQuery(java.lang.String queryString)

set the textual query string for the query. The syntax of this string depends on the requirements of the retrieval service used in the pipeline, so every string is accepted here and no syntax checking is done.

Parameters:

queryString - textual query string.

Returns:

"this"

setQueryAttribute

public QueryBuilder setQueryAttribute(java.lang.String attributeName,
                             java.lang.Object... values)

set attribute in "queryAttribute" part of request.

Parameters:

attributeName - attribute name

values - values.

Returns:

"this"

setMaxCount

public QueryBuilder setMaxCount(int maxCount)

set the maximum search result size for the query.

Parameters:

maxCount - maximum result count.

Returns:

"this"

setOffset

public QueryBuilder setOffset(int offset)

set the search result offset for the query, i.e. the number of most relevant result objects to skip in the result list. Use this to implement paging on the result set.

Parameters:

offset - result offset

Returns:

"this"

setThreshold

public QueryBuilder setThreshold(double threshold)

set the threshold for the relevance value of search results, i.e. only results having a relevance of at least the threshold value, should be returned to the client. Relevances are usually number between 0.0 (completely irrelevant to the query) and 1.0 (perfect match), so the threshold value should be from the same range. However, as the search API does not know about details of the used search engine, no checking is done and all double values are accepted.

Parameters:

threshold - relevance threshold value.

Returns:

"this"

setLanguage

public QueryBuilder setLanguage(java.lang.String language)

set the language parameter for the query. This is used by services/pipelets that have a language specific functionality (e.g. stemming, spellchecking, recognition of currency values ...) to configure the language of the query string. Usually the possible values are the standard locale codes like "en", "de".

Parameters:

language - a language code.

Returns:

"this"

setIndexName

public QueryBuilder setIndexName(java.lang.String indexName)

set the index name for the query. Some search engine integrations may be capable of managing multiple seperated indexes and use this parameter to select the index to search in.

Parameters:

indexName - index name

Returns:

"this"

setResultAttributes

public QueryBuilder setResultAttributes(java.lang.String... attributes)

set names attributes to appear in result records.

Parameters:

attributes - attribute names.

Returns:

"this"

setRanking

public QueryBuilder setRanking(Any ranking)

Parameters:

ranking - set ranking configuration

Returns:

"this"

addSortBy

public QueryBuilder addSortBy(java.lang.String attribute,
                     QueryConstants.SortOrder mode)

add an sortby specification.

Parameters:

attribute - an attribute to order by

mode - the order direction (ascending or descending)

Returns:

"this"

addHighlightByAttribute

public QueryBuilder addHighlightByAttribute(java.lang.String... attributes)

Add a configuration for each attribute to highlight AnySeq.

Parameters:

attributes - the attributes.

Returns:

QueryBuilder.

addHighlightByConfig

public QueryBuilder addHighlightByConfig(java.lang.String attribute,
                                AnyMap config)

Add the given configuration for the given attribute to highlight AnySeq.

Parameters:

attribute - the attribute.

config - the configuration as AnyMap.

Returns:

QueryBuilder.

addFacetByAttribute

public QueryBuilder addFacetByAttribute(java.lang.String attribute,
                               int maxCount,
                               java.lang.String sortCriterion,
                               QueryConstants.SortOrder sortOrder)

add facetby config for attribute with maxcount and sort config for facets.

Parameters:

attribute - attribute name

maxCount - max number of facets to return

sortCriterion - sort criterion for facets, e.g. "value" or "count"

sortOrder - sort order for facets

Returns:

"this"

addFacetByAttribute

public QueryBuilder addFacetByAttribute(java.lang.String attribute,
                               int maxCount)

add facetby config for attribute with maxcount.

Parameters:

attribute - attribute name

maxCount - max number of facets to return

Returns:

"this"

addFacetByConfig

public QueryBuilder addFacetByConfig(java.lang.String attribute,
                            AnyMap config)

Parameters:

attribute - attribute name

config - facetBy config for this attribute

Returns:

"this"

addOneOfFilter

public QueryBuilder addOneOfFilter(java.lang.String attribute,
                          java.lang.Object... values)

add a "oneOf" filter of allowed values for an attribute.

Parameters:

attribute - attribute name

values - allowed values

Returns:

"this"

addAllOfFilter

public QueryBuilder addAllOfFilter(java.lang.String attribute,
                          java.lang.Object... values)

add a "allOf" filter of required values for an attribute.

Parameters:

attribute - attribute name

values - required values

Returns:

"this"

addNoneOfFilter

public QueryBuilder addNoneOfFilter(java.lang.String attribute,
                           java.lang.Object... values)

add a "noneOf" filter of forbidden values for an attribute.

Parameters:

attribute - attribute name

values - forbidden values

Returns:

"this"

addAtLeastFilter

public QueryBuilder addAtLeastFilter(java.lang.String attribute,
                            java.lang.Object value)

add a "atLeast" filter for the minimum (inclusive lower bound) value of an attribute.

Parameters:

attribute - attribute name

value - minimum value

Returns:

"this"

addAtMostFilter

public QueryBuilder addAtMostFilter(java.lang.String attribute,
                           java.lang.Object value)

add a "atMost" filter for the maximum (inclusive upper bound) value of an attribute.

Parameters:

attribute - attribute name

value - maximum value

Returns:

"this"

addGreaterThanFilter

public QueryBuilder addGreaterThanFilter(java.lang.String attribute,
                                java.lang.Object value)

add a "greaterThan" filter for the exclusive lower bound value of an attribute.

Parameters:

attribute - attribute name

value - exclusive lower bound value

Returns:

"this"

addLessThanFilter

public QueryBuilder addLessThanFilter(java.lang.String attribute,
                             java.lang.Object value)

add a "lessThan" filter for the exclusive upper bound value of an attribute.

Parameters:

attribute - attribute name

value - exclusive upper bound value

Returns:

"this"

addRangeFilter

public QueryBuilder addRangeFilter(java.lang.String attribute,
                          java.lang.Object lowerBound,
                          java.lang.Object upperBound)

add range filter (inclusive). bounds may be null.

Parameters:

attribute - attribute name

lowerBound - lower bound of range

upperBound - upper bound of range

Returns:

"this"

addListFilter

public QueryBuilder addListFilter(java.lang.String attribute,
                         java.lang.String filterType,
                         java.lang.Object... values)

add a filter with a value list.

Parameters:

attribute - attribute name

filterType - filter type

values - filter values

Returns:

"this"

addBoundFilter

public QueryBuilder addBoundFilter(java.lang.String attribute,
                          java.lang.String filterType,
                          java.lang.Object boundValue)

add a filter with a single value bound.

Parameters:

attribute - attribute name

filterType - filter type

boundValue - value

Returns:

"this"

addFilter

public QueryBuilder addFilter(java.lang.String attribute,
                     AnyMap filter)

add a arbitrary complex filter object for an attribute.

Parameters:

attribute - attribute name

filter - filter

Returns:

"this"

addAttributeConfig

public QueryBuilder addAttributeConfig(java.lang.String parameterName,
                              java.lang.String attributeName,
                              AnyMap config)

add a complex parameter (ie. the given config) for an attribute: the parameter will be a sequence of maps, each containing the attribute name under key "attribute". e.g.

 {Seq key='parameterName'
    ${config-map
      {Value key='attribute' value='$attributeName'}
    }
 }
 

Parameters:

parameterName - parameter name

attributeName - attribute name

config - the map which is added to the seq named param and inti which the attribute string/value is added.

Returns:

"this"

setParameter

public QueryBuilder setParameter(java.lang.String name,
                        java.lang.String value)

sets a single parameter value.

Parameters:

name - parameter name

value - parameter value

Returns:

"this"

addParameter

public QueryBuilder addParameter(java.lang.String name,
                        java.lang.String value)

adds to a parameter sequence.

Parameters:

name - parameter name

value - parameter value

Returns:

"this"

setAttachment

public QueryBuilder setAttachment(java.lang.String name,
                         byte[] attachment)

add attachment to query. Keep in mind that attachments are kept in memory in search processig, so you should care about not adding large attachments.

Parameters:

name - attachment name

attachment - attachment content

Returns:

"this"

executeRequest

public ResultAccessor executeRequest(SearchService searchService)
                              throws ProcessingException

execute query on given search service and wrap result in high level result helper.

Parameters:

searchService - search service instance.

Returns:

search result.

Throws:

ProcessingException - any error while processing the search

executeRequestXml

public org.w3c.dom.Document executeRequestXml(SearchService searchService)
                                       throws javax.xml.parsers.ParserConfigurationException

execute query on given search service and return search result as XML DOM document.

Parameters:

searchService - search service instance.

Returns:

search result, or XML description of error that occurred in searcuh

Throws:

javax.xml.parsers.ParserConfigurationException - error creating the XML result

executeRequestXmlString

public java.lang.String executeRequestXmlString(SearchService searchService)
                                         throws javax.xml.parsers.ParserConfigurationException

execute query on given search service and return search result as XML string.

Parameters:

searchService - search service instance.

Returns:

search result, or XML description of error that occurred in search

Throws:

javax.xml.parsers.ParserConfigurationException - error creating the XML result

getQuery

public Record getQuery()

access underlying query record for advanced manipulation.

Returns:

query record.

getMetadata

public AnyMap getMetadata()

access underlying query record metadata for advanced manipulation.

Returns:

query record metadata.

getWorkflowName

public java.lang.String getWorkflowName()

the name of the search pipeline to use.

Returns:

pipeline name.

getFactory

public DataFactory getFactory()

Returns:

data factory used.

addResultAttributes

public QueryBuilder addResultAttributes(java.lang.String... fieldNames)

adds the given fieldNames as result field(s).

addGroupByAttribute

public QueryBuilder addGroupByAttribute(java.lang.String groupCommand,
                               java.lang.String attribute,
                               int maxcount)

Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupCommand.

Parameters:

groupCommand - the group command.

attribute - the attribute.

maxcount - the max count.

Returns:

QueryBuilder.

addGroupByConfig

public QueryBuilder addGroupByConfig(java.lang.String groupCommand,
                            AnyMap config)

Add a group configuration to RecordMetadata/groupby/groupCommand.

Parameters:

groupCommand - the group command.

config - the configuration

Returns:

QueryBuilder.

addGroupByAttribute

public QueryBuilder addGroupByAttribute(java.lang.String groupName,
                               java.lang.String groupCommand,
                               java.lang.String attribute,
                               int maxcount)

Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupName/groupCommand.

Parameters:

groupName - the group name.

groupCommand - the group command.

attribute - the attribute.

maxcount - the maxcount.

Returns:

QueryBuilder.

addGroupByConfig

public QueryBuilder addGroupByConfig(java.lang.String groupName,
                            java.lang.String groupCommand,
                            AnyMap config)

Add a group configuration to RecordMetadata/groupby/groupName/groupCommand.

Parameters:

groupName - group name.

groupCommand - the group command.

config - the configuration.

Returns:

QueryBuilder.

addGroupByAttribute

public QueryBuilder addGroupByAttribute(java.lang.String groupName,
                               java.lang.String groupCommand,
                               java.lang.String attribute,
                               int maxcount,
                               java.lang.String asMainResult)

Add a group configuration with attribute and maxcount to RecordMetadata/groupby/groupName/groupCommand and set asMainResult within RecordMetadata/groupby.

Parameters:

groupName - the group name.

groupCommand - the group command.

attribute - the attribute.

maxcount - the maxcount.

asMainResult - the group name which should be used as main result.

Returns:

QueryBuilder.

addGroupByConfig

public QueryBuilder addGroupByConfig(java.lang.String groupName,
                            java.lang.String groupCommand,
                            AnyMap config,
                            java.lang.String asMainResult)

Add a group configuration to RecordMetadata/groupby/groupName/groupCommand and set asMainResult within RecordMetadata/groupby.

Parameters:

groupName - the group name.

groupCommand - the command name.

config - the configuration.

asMainResult - the group name which should be used as main result.

Returns:

QueryBuilder