Query syntax in REST api calls
As of 3.4.0.RC5 the admin rest api has the possibility to specify a "query" parameter. This query parameter provides filter rules to apply when retrieving data. With 3.4.0.RC5, it is restricted to user retrieval (listUser call), but there is no hard reason for that, other than it has to be added in the other entity retrievals as well (listDomains).
This document describes the query syntax and briefly how it is implemented.
2. Query syntax
The query syntax is the same as the lucene query syntax with some restrictions.
- Single terms, phrase terms
- Field specification (with some extensions)
- Wildcard searches
- Boolean operators (OR, AND, '+', NOT, '-')
- Field grouping
Not supported is:
- Regular expression searches
- Fuzzy searches
- Proximity searches
- Range searches
- Term boosting
NOTE, that currently in general, searches are executed case insensitive. So searching for "BOB", "bob" or "BoB" will all match the value "bob" in the field.
2.1.1. Single terms, phrase terms
Single term: a single word like "test" or "Bob"
Phrase term: a group of words surrounded with double quotes like "Hi Bob"
If multiple "single" terms are specified in a query, they are searched in the corresponding field in no particular order or place. The single terms "Bob" and "Hello" will match a field containing "Hello, my name is Bob" as well as a field with "Bob says: Hello".
Phrase terms on the other hand must be found exactly the way they're specified. The phrase query "Hi Bob" only match only field content "Hi Bob", not "Hi, I'm Bob".
2.1.2. Field specification (and extension)
A field can be specified to search in. In fact, if no field is specified, it falls back to a "default" field or "all fields".
Query with explicit field:
Query with default field:
Currently (3.4.0.RC5) "no field" is mapped to "default field" which in turn is mapped to "all fields available". Thus, the last query above is the same as:
The field syntax of lucene has been extended in our case to have support for some "hierarchical" or "qualified" field names. A field name essentially consists of an entity path and finally the name of the field in the entity.
user, field in entity:
It's possible to match all fields in an entity like this:
Note that a specified field always only affects the directly following single or phrase term!
This example shows, that the default behaviour may be misleading at first sight. This query will search for
bob in the
name field and the term
brown in all fields of all entites involved in the search!
It is essentially the same as:
To search the name Bob brown in the
user.name field, use this syntax:
This will make sure, that the query must match the terms 'bob' and 'brown' both in the name field. Alternatively, a phrase query could be used, which however would only match the name in the exact order given as mentionned before.
2.1.3. Wildcard searches
Single and multiple character wildcards are supported in single terms but not in phrase terms:
Single character wildcard:
? (means: must match exactly one character at this position)
Multiple character wildcard:
* (means: can match zero or more characters at this position)
ali as well as
alicante but not
Note: Currently, wildcard characters must not appear at first position.
2.1.4. Boolean Operators
Terms can be combined with boolean operators. In fact, as soon as more than one term appears, they are combined with boolean operators, whether explicitly specified or not.
The default operator is
AND, which means, by default all terms must appear in their corresponding fields.
18.104.22.168. OR (or '||')
OR operator combines two terms and makes both of them a "should match" term.
Bob OR Bib
22.214.171.124. AND (or '&&')
AND operator combines two terms and makes both of them a "must match" term.
Bob AND Brown
Similar to the
AND operator, in that the term prefixed with
+ is a "must match" term, but does not influence other terms.
126.96.36.199. NOT (or '!')
Excludes matches, where the term afterwards appears.
+Bob NOT Brawn
Prohibit operator excludes matches, where the term afterwards appears.
188.8.131.52. Additional important informations about boolean operators
Note: Boolean operators such as
OR are not following the same precedence rules as they do in most systems or programming languages, like
AND has precedence over
OR. Instead, in query syntax, the operators only affect the following term. In essence, it is simpler to imagine how it works, when looking at the
- operators: They only affect the term prefixed with.
Bob OR Bab AND Brown
In most modern programming languages,
AND has precedence and thus would in fact be executed as
Bob OR (Bab AND Brown). In our query syntax, this is not the case. Instead it is executed as
Bob (should match)
Bab (should match)
+Brown (must match).
Multiple (boolean) clauses can be grouped by using paranthesis:
(Bob OR Bab) AND Brown
2.1.6. Field Grouping
To prevent the need to always specify a field name, terms can be grouped and assigned the same field: