Filters
Filters can be applied to search queries.
Filter 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 constraints 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.
Parameter | Description | Default |
---|---|---|
|
Name of the field to constrain. |
|
|
The value that the filter should match. |
|
|
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:
* See "`Optional` operators" below for more details. |
|
|
Whether the filter is hidden or not. |
|
|
Whether filter is to exclude (negate) or not. |
|
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, 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.
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>