Query Language
All standard list resources may be filtered by supplying a search expression via
the q query parameter. The search expression is a subset of—plus a few
extensions to—the Lucene Query Parser
Syntax.
Filtering is always case-insensitive!
Terms
A term is a single word to search for. Single terms are always stemmed—that
is, the terms are processed in such a way that the term company will match
both "company" and "companies", for instance.
company
Single terms apply to any of an entity's properties. In the previous example, it
does not matter if a name or description property contained the word
"companies"; the query will match either way.
Another kind of term is the phrase term, which finds several terms next to each other, no matter where in a sentence the phrase appears; however, this is currently not yet supported by the API.
Fields
Terms may also be prefixed by the name of a property, called a field. This kind of terms are never stemmed.
name:company
Nested properties is specified by separating the property names with a dot:
receipt.reference:emma
Wildcards
It's also possible to search for all terms that begin with a specified term prefix. This is indicated by ending the prefix with an asterisk. Note, however, that this only works reliable for unstemmed terms, so make sure that you also use a field prefix in this case.
name:comp*
Boolean combinations
Multiple terms may be combined using boolean operators. And, Or, Not, Required and Prohibited are supported.
Or (union) is the default if several whitespace-separated terms are specified:
company person
company OR person
company || person
The queries above find entities that contain either "company" or "person" (or both) in any of its properties.
The And (intersection) operator requires that a matching entity includes both terms.
company AND person
company && person
The queries above find entities that contain both "company" and "person" in any of its properties.
Not (difference) is used to exclude a term from the result set.
company NOT person
company ! person
The queries above find entities that contain "company" but not "person". Another way to express the same query is to use the Prohibited operator:
company -person
You can also mark a term as Required by using a plus sign in front of it:
company +person
It's very similar to And. Some may even say "identical".
Expressions may also be grouped using parentheses:
company AND (person OR employee)
The query above finds all entities that contains "company" and either of "person" or "employee" (or both).
Field relations
It's also possible to query the exact value of properties, and not just words in
a string field. The query parser supports the <, <=, =, >= and >
relations, and ranges (inclusive or exclusive).
price<100
price<=100
price=100
price>=100
price>100
Ranges uses a colon and two values enclosed by brackets. [ and ] means
inclusive; { and } means exclusive. The expressions
price:[10 20]
price:{10 20}
price:[10 20}
are thus equivalent to the following queries:
price>=10 AND price<=20
price>10 AND price<20
price>=10 AND price<20
Sometimes, the value must be quoted in order to confirm to the syntax. For instance, when searching for dates, the date must be enclosed in quotes:
created<"2014-01-28T09:00:43.476Z"
Escaping
Finally, special characters may be escaped using a backslash:
name="Pete \"Maverick\" Mitchell"