Filters

You can apply filters to search queries.

Filter formats

Filters can have the following formats.

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 query tag by using the ampersand (&) as a separator character. 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 in 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. 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

App Studio supports range queries for numbers, dates and strings. For example, filters=salary[1000,100000] searches 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"]

  • 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" ... >
    <query:filter field="myField" value="myValue" />
</search:query>

Which constrains the query to all documents with the value “myValue” in myField. It is not possible to use ranges with the query:filter tag. The value is always interpreted as a string.

Table 1. Tag attributes
Attribute Description Default

field (java.lang.String)

Name of the field to constrain.

none

value (java.lang.Object)

The value that the filter should match.

none

optional (java.lang.String)

In the case where multiple filters are being applied, this attribute may be used to determine how the filters may be combined to produce the desired query term. Values for this attribute are:

  • field

  • value

  • none

See Optional logical operators below for more details.

none

hidden (java.lang.Boolean)

Whether the filter is hidden or not.

false

exclude (java.lang.Boolean)

Whether filter is to exclude (negate) or not.

false

Optional logical operators

Use the optional tag attribute for a filter to specify a connective logical operator for the filter. This tells App Studio how to combine a filter with other filters.

Values for the optional attribute are:

  • field

  • value

  • none

For example, if the commonality of the query as prescribed by the filters is found through field, then in this case you set the optional attribute to field.

See the corresponding Java enumerations below.

field – Fully optional condition

To make a given filter’s condition fully optional, use the field flag. This means 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))

value – Values within a given field

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

This is the recommended approach when using checkboxes to select values within a facet. In that case, the default behavior is to allow the user to select multiple options which are 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 results in a query like: (foo:bar AND (marx:groucho OR marx:harpo))

none – Logical conjunction (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.

Filter syntax quick reference

A quick reference to App Studio query filters is shown below.

  • <group-number> is an integer value denoting a grouping of filter constraints.

  • <field-name> is a the name of the field to apply the constraint to. A valid field name is one that matches the regular expression [A-Za-z_][A-Za-z_0-9\-\.: ].

  • <display-value> is an optional label to attach to the filter.

  • <filter-value> is the constraint to be applied to the specified field.

<filter-expression> ::= <field-expression> <group-expression> <value-expression <display-expression>
<field-expression> ::= <exclusion-expression> <field-optional-expression> <field-name>
<exclusion-expression> ::= "-" | ""
<field-optional-expression> ::= "~" | ""

<group-expression> ::= "(" <group-number> ")"
<group-number> ::= <digit> | <digit> <group-number>

<field-name> ::= <field-name-prefix> <field-name-suffix>
<field-name-prefix> ::= <letter> | "_"
<field-name-suffix> ::= <field-symbol> | <field-symbol> <field-name-suffix>
<field-symbol> ::= <letter> | <digit> | "_" | "-" | "." | ":" | " " | ""

<value-expression> ::= <value-bracket-left> <filter-value> <value-bracket-right>
<value-bracket-left> ::= "[" | "("
<value-bracket-right> ::= "]" | ")"

<filter-value> ::= <value> | <range-value>

<value> ::= <string-expression> | <numeric-value> | <date-value>

<string-expression> ::= <partial-match> <string-value> <partial-match>
<string-value> ::= '"' <text> '"' | "'" <text> "'"
<partial-match> ::= '' | '*'

<numeric-value> ::= <floating-point> | <integer>
<number-sequence> ::= <digit> | <number-sequence> <digit>
<integer> ::= "0" | <positive-digit> <number-sequence>
<floating-point> ::= <integer> | <integer> "." <number-sequence>

<date-value> ::= <four-digits> "-" <two-digits> "-" <two-digits> "'T'" <two-digits> ":" <two-digits> ":" <two-digits>
<two-digits> ::= <digit> <digit>
<four-digits> ::= <two-digits> <two-digits>

<range-value> ::= <value> "," <value> | "," <value> | <value> ","

<display-expression-opt> ::= "" | "[" <display-expression> "]"
<display-expression> ::= "[" '"' <display-value> '"' "]" | "[" "'" <display-value> "'" "]"
where

<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G"
       | "H" | "I" | "J" | "K" | "L" | "M" | "N"
       | "O" | "P" | "Q" | "R" | "S" | "T" | "U"
       | "V" | "W" | "X" | "Y" | "Z"
       | "a" | "b" | "c" | "d" | "e" | "f" | "g"
       | "h" | "i" | "j" | "k" | "l" | "m" | "n"
       | "o" | "p" | "q" | "r" | "s" | "t" | "u"
       | "v" | "w" | "x" | "y" | "z" ;

<positive-digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<digit> ::= "0" | <positive-digit>