Skip to main content

Cookie control banner

Necessary Cookies
These cookies are necessary for this website to function correctly. They are set when you perform certain actions on the site, such as creating an account, logging in, changing your privacy preferences or submitting a form. You can block these cookies in your browser, but this will stop parts of the site from working properly.
Functional Cookies
These cookies allow the website to provide extra functionality and more personalised experiences. They may be set by us or by third party providers whose services we have added to our pages. If you choose not to allow these cookies, these services may not work correctly.
Analytical Cookies
These cookies record anonymous data on how visitors use our website to help us monitor how well our website works. This data includes how many people have looked at specific pages, how long visitors stay on the site, and what devices they use. We use this data to identify changes that we could make to improve your experience and make our website more efficient.
Marketing Cookies
We set some cookies so you are shown more relevant marketing content. These include cookies from third-party advertising networks to show you different adverts on their services if you have previously visited our site. If you choose not to allow these cookies, you may experience less relevant advertising on other sites.
Browse Documentation

Query operators

Created by r.turner, last modified by zengenti on 24 Sep 2021
  • And
  • Or
  • Not
  • Between
  • Contains
  • endsWith
  • equalTo
  • Exists
  • freeText
  • greaterThan
  • greaterThanOrEqualTo
  • In
  • lessThan
  • lessThanOrEqualTo
  • startsWith
  • distanceWithin

Logical operators

And

This would return any document where first is 1 AND second is 2.

JSON
{ "where": [{ "and": [{ "field": "first", "equalTo": 1 }, { "field": "second", "equalTo": 2 }] }] }

The And operator is the default logical operator and is not required to be specified explicitly.

JSON
{ "where": [{ "field": "first", "equalTo": 1 }, { "field": "second", "equalTo": 2 }] }

Or

The example would return any document where first is 1 OR second is 2.

JSON
{ "where": [{ "or": [{ "field": "first", "equalTo": 1 }, { "field": "second", "equalTo": 2 }] }] }

Not

The not expects an inner operator so in the example any document where first is NOT equal to 7 would be returned.

JSON
{ "where": [{ "not": { "field": "first", "equalTo": 7 } }] }

Relational & equality operators

Between

In this example, if our field is between 18 and 45 inclusive it would match.

JSON
{ "where": [{ "field": "age", "between": [18, 45] }] }

Contains

This would match on a field called description containing the phrase batman.  This operator can also use ? and * wildcards. However, it only searches the first 8,000 characters and can be slow to search longer fields. To search efficiently for complete words across the whole field use the freeText operator.

If you carried out a search with the term bat or man or batma, each of the searches would return results for batman as the terms are contained within the word.

JSON
{ "where": [{ "field": "description", "contains": "batman" }] }

Multi word

If your description field contained the phrase batman begins, and you carried out a search containing multiple words, results would be returned for batman, batman beg, but not for batman ends.

JSON
{ "where": [{ "field": "description", "contains": "batman begins" }] }

endsWith

This would find any item that has a field called wordField with a value ending with ing.

JSON
{ "where": [{ "field": "wordField", "endsWith": "ing" }] }

equalTo

This would find any item that has a field called blends with a value exactly matching 5. For string fields, the comparison is case-insensitive.

JSON
{ "where": [{ "field": "blends", "equalTo": 5 }] }

Exists

In the example any document that has a field called fieldName and would be returned. Documents where fieldName has some content would also be returned.

You can use a value of false if you want documents that do not contain a given field or where the field is empty or null.

JSON
{ "where": [{ "field": "fieldName", "exists": true }] }

freeText

In the example the field synopsis is searched upon for all words that match gotham and dark and knight.

JSON
{ "where": [{ "field": "synopsis", "freeText": "gotham dark knight" }] }

Operator 'or'

By default freeText matches all words in the search term. If you want results that match one or more words in the search term the operator can be set to "or".  Results that match the most number of words in the search term are ranked higher than documents that match fewer words.

JSON
{ "where":[ { "field":"synopsis", "freeText":{ "term":"gotham dark knight", "operator":"or" } } ] }

Fuzzy

Free text searches can also be made fuzzy, by specifying fuzzy true and passing the search value as term.

JSON
{ "where":[ { "field":"synopsis", "freeText":{ "term": "gotham dark knight", "fuzzy": true } } ] }

A fuzzy search returns results that contain terms similar to the search term. The similarity is measured by a Levenshtein edit distance.

An edit distance is the number of one-character changes needed to turn one term into another. These changes can include:

  • Changing a character (box → fox)
  • Removing a character (black → lack)
  • Inserting a character (sic → sick)
  • Transposing two adjacent characters (act → cat)

To find similar terms, the fuzzy query creates a set of all possible variations, or expansions, of the search term within a specified edit distance. The query then returns exact matches for each expansion.

We use the preferred auto setting for fuzziness, this means that the edit distance changes dependant on the length of the search terms.

greaterThan

In the example any item that has a field called first and a value that is greater than 7 would be returned.

JSON
{ "where": [{ "field": "first", "greaterThan": 7 }] }

greaterThanOrEqualTo

In the example any item that has a field called first and a value that is greater than or equal to 7 would be returned.

JSON
{ "where": [{ "field": "first", "greaterThanOrEqualTo": 7 }] }

In

In the example any document where the field first is equal to 1,7 or 11 would be returned. The values should be of the same type, in this case integer.

JSON
{ "where": [{ "field": "first", "in": [1, 7, 11] }] }

lessThan

In the example any item that has a field called first and a value that is less than 7 would be returned.

JSON
{ "where": [{ "field": "first", "lessThan": 7 }] }

lessThanOrEqualTo

In the example any item that has a field called first and a value that is less than or equal to 7 would be returned.

JSON
{ "where": [{ "field": "first", "lessThanOrEqualTo": 7 }] }

startsWith

In the example if the name field contains a value starting with war it would match.

JSON
{ "where": [{ "field": "name", "startsWith": "war" }] }

distanceWithin

In the example any locations within a 10 mile radius of the specified location would match.

JSON
{ "where": [{ "field": "location", "distanceWithin": { "lat": "52.377", "lon": "-2.749", "distance": "10mi" } }] }