Internal Documentation

This document may change at any time without prior notice.
Changes may break backwards compatibility.
Do not rely on it!

Query syntax in REST api calls

1. Purpose

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.

Supported is:

  • Single terms, phrase terms
  • Field specification (with some extensions)
  • Wildcard searches
  • Boolean operators (OR, AND, '+', NOT, '-')
  • Grouping
  • 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:

username:bob@unblu.com

Query with default field:

bob@unblu.com

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:

*:bob@unblu.com

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.

Example:

user.username:bob@unblu.com

Entity: user, field in entity: username

It's possible to match all fields in an entity like this:

user.*:bob

Note that a specified field always only affects the directly following single or phrase term!

Example:

user.name:bob brown

This example shows, that the default behaviour may be misleading at first sight. This query will search for bob in the user's name field and the term brown in all fields of all entites involved in the search!
It is essentially the same as:

user.name:bob *:brown

To search the name Bob brown in the user.name field, use this syntax:

user.name:bob user.name:brown

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)

Examples:

a?i* matches ali as well as alicante but not aiko

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.

2.1.4.1. OR (or '||')

The OR operator combines two terms and makes both of them a "should match" term.

Bob OR Bib

2.1.4.2. AND (or '&&')

The AND operator combines two terms and makes both of them a "must match" term.

Bob AND Brown

2.1.4.3. +

Similar to the AND operator, in that the term prefixed with + is a "must match" term, but does not influence other terms.

+Bob +Brown

2.1.4.4. NOT (or '!')

Excludes matches, where the term afterwards appears.

+Bob NOT Brawn

2.1.4.5. -

Prohibit operator excludes matches, where the term afterwards appears.

-Brawn

2.1.4.6. Additional important informations about boolean operators

Note: Boolean operators such as AND or 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 + and - operators: They only affect the term prefixed with.

Example:

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

2.1.5. Grouping

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:

user.name:(Bob AND Brown)

How can we help?

Chat with us and we will take you through our site!

Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.