Looking for the old docs site? You can still view it for a limited time here.

Formulate a Query

The Appkit Query tag (<search:query>) instantiates a search query that can be submitted to the underlying search platform.

Usage

This example shows how to create a Query in a JSP page using the Query tag. The QueryTag can use all applicable parameters from the query string (HTTP request) to create a Query object.

As an example, if the URL of the page is http://intranet/search?q=guidelines&rpp=10, then the word 'guidelines' would be set as the query term, and the query would instruct the search engine to limit the results per page (rpp) to 10.

This example shows how you can override the rpp (short form of the resultsPerPage attribute) to fix how many results should be displayed per page, or override the value specified in the URL query string. To do this, add the long-form name of the attribute to override to the Query tag:

<search:query var="query" parameters="*" resultsPerPage="5" />

You can also create a Query instance from another one using the from attribute for cloning the former:

<search:query var="query" from="${otherQuery}" resultsPerPage="5" />
Note
Adding the query parameter query or modifiedQuery means that the value is fixed for all queries, that is, the value overrides any parameters inherited from the URL query string.

Multilevel sorting is supported. To sort by multiple levels using the QueryTag use & to separate the values, for example, to sort by price ascending and then sku descending, use sorts="+price&-sku". To do the same using the URL query string use multiple instances of the s parameter, for example, ?&s=+price&s=-sku.

Short format

Filters are specified using the format fieldName[value]['display name']. The ['display name'] part is optional in all cases.

For example, adding filters="locations['san francisco']" to the Query tag restricts the results to those with san francisco appearing in the locations field.

Multiple filters can be specified on the QueryTag by using the separator characters &. For example, filter="locations['san francisco']&people['obama']" would restrict the results to those with the value san francisco appearing in the locations field and the value obama appearing the people field.

Multiple filters can be specified with the URL query string by adding multiple f parameters:

?f=locations['san francisco']&f=people['obama']
Important
If the value is a String it should be surrounded by quotes, all other primitives and dates should have the quotes omitted see below (URL query parameter examples).

For example:

  • Filtering on String: &f=stringField['My String']["String example"]

  • Filtering on Integer:`&f=integerField[123]["Integer example"]`

  • Filtering on Double: &f=doubleOrFloatField[123.45]["Double example"]

Long format

When the query value of the filter differs from the display value the format is slightly different to accommodate this extra information: filters="fieldName[value]["display name"].

Range format

Appkit supports range queries for numbers, dates and strings. For example filters=salary[1000,100000] will search the salary field for values between 1000 and 100000.

Date format

To filter by date (on date fields allowing range queries) use the DateFilter format (in all cases the display name is optional):

  • To Filter on dates before the provided Date use: filters=dateFieldName[,yyyy-MM-dd’T’HH:mm:ss]["Before the given date"]

  • To Filter on dates after the provided Date use: filters=dateFieldName[yyyy-MM-dd’T’HH:mm:ss,]["After the given date"]

  • To Filter on dates within a given range use: filters=dateFieldName[yyyy-MM-dd’T’HH:mm:ss,yyyy-MM-dd’T’HH:mm:ss]["Date range"]

  • From 2.10 onwards, to exclude the upper or lower limit of a date range it is possible to to replace the [ and ] with a ( and ). For example: filters=dateFieldName[yyyy-MM-dd’T’HH:mm:ss,yyyy-MM-dd’T’HH:mm:ss)["Date range excluding upper limit"]

Invariant filters

To configure a query with invariant constraints, you can add filter tags to the body of the query tag like so:

<search:query var="query" ... >
    <search:filter field="myField" value="myValue" />
</search:query>

This constrains the query to all documents with the value "myValue" in "myField". It is not possible to use ranges with the <search:filter> tag. The value will always be interpreted as a string.

Optional Operators

Appkit supports combining filters using different logical operators (connectives).

Enabling Logical Disjunction for Filters (OR connectives)

There are two ways of combining a set of filters using an inclusive disjunction where each filter represents an logically optional condition whilst keeping filters individually distinct. Each filter’s optional state is represented as being either 'value', 'field' or 'none', with the corresponding Java Enumerations below.

'value' - Values within a given field

Filters for the same field that are 'value' optional will be combined using an OR operator. This group of filters will then be combined with the rest of the filters using a logical AND.

This would be the recommended approach when using checkboxes to select values within a facet. In that case the default behaviour would be to allow the user to select multiple options which would be combined using an OR. This is encoded in the query URL using an asterisk after the filter value:

&f=foo['bar']&f=marx['groucho']*&f=marx['harpo']*

This would result in a query like: (foo:bar AND (marx:groucho OR marx:harpo))

'field' - Fully optional condition

To make a given filter’s condition fully optional you would use the 'field' flag. This would mean that these filters are combined with the rest using an OR.

This is encoded in the query URL using a tilde before the field name:

&f=foo['bar']&f=~marx['groucho']&f=~marx['harpo']*

This would result in a query like: foo:bar) OR (marx:groucho) OR (marx:harpo

'none' - Logical Conjunction, default (AND)

By default, individual filters (&f=) are applied to the query using logical conjunction (AND). This means that the documents returned must satisfy both filter conditions. This is the default connective.

Alternative way to add Filters

Another way to add Filters to a Query is using dynamic attributes on the Query tag. Any parameters other than the ones detailed above will be treated as field names, and their corresponding value as a filter expression.

For example, this Query tag would create a query from the URL query string and additionally add two hidden filters 1) the source field should contain the value FT and 2) the bestbets field should be true:

<search:query var="query" parameters="*" resultsPerPage="5" source="FT" bestbets="true" />

To add exclude filters prefix the filter name with not-. This would add a filter that excludes all documents where the source field contains the value FT:

<search:query var="query" parameters="*" not-source="FT" />

Tag body

The body of the Query tag can be used to specify which Processors should be applied to the Query before submitting it to the underlying search platform. Multiple Processor tags can be specified for sequential processing of the Query. Only Processors parameterized with the Query class are allowed here.

<search:query var="query" parameters="*" maxResults="5">
    <search:processor className="twigkit.search.processors.query.ProcessorName1" attr1="value1" attr2="value2" />
    <search:processor className="twigkit.search.processors.query.ProcessorName2" attr1="value1" attr2="value2" />
</search:query>

Special Cases

This example, just like the one above, shows how to create a Query in a JSP page where all applicable properties from the query string (HTTP request) are used to populate the Query object.

However, in this case you want to modify the query before submitting it to the search engine without the user knowing that the query has been altered with the modifiedQuery parameter. This technique can be used to annotate the query with additional, search engine-specific query operators.

For example, if you are using the FAST Platform, this technique can be used to rewrite the query into FQL as the example below illustrates:

<search:query var="query" parameters="*" modifiedQuery="AND(author:'${param.query}', 'title:'Nature')"
type="advanced" />

Groups

grouping (java.lang.Boolean)
If the grouping attribute is set to true then Filter grouping is enabled for this query.
Default: false