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
    Parameter 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` 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

    When using the optional filter (see above), App Studio supports combining filters using different logical operators (connectives).

    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 the optional attribute in this case is set to "field".

    See the corresponding Java enumerations below.

    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))

    value – Values within a given field

    Filters for the same field that are value optional is 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>