2.1JSON Superset

GROQ’s syntax is a superset of JSON, so any valid JSON value is a valid GROQ expression (that simply returns the given value). Below are a few examples of JSON values:

"Hi! 👋"

["An", "array", "of", "strings"]

{
  "array": ["string", 3.14, true, null],
  "boolean": true,
  "number": 3.14,
  "null": null,
  "object": {"key": "value"},
  "string": "Hi! 👋"
}

2.2White Space

Whitespace is not significant in GROQ, except for acting as a token separator and comment terminator. Any sequence of the following characters is considered whitespace.

Whitespace inside a string literal is interpreted as-is.

2.3Comments

Comments serve as query documentation, and are ignored by the parser. They start with // and run to the end of the line:

Example № 2{
  // Comments can be on a separate line
  "key": "value" // Or at the end of a line
}

Comments cannot start inside a string literal.

Example № 3{
  "key // This isn't a comment": "value"
}

2.4Identifier

Identifiers are used to name entities such as parameters, attributes and functions. An identifier is a sequence of one or more letters and digits. The first character in an identifier must be a letter.

2.5Digits

GROQ uses decimal digits (0-9) and hexadecimal digits (0-9, a-f) in various places.

2.6Expression

An Expression is either a literal (e.g. 15), a simple expression (e.g. @), or a compound expression (e.g. *[name == "Michael"]) or an operator call (e.g. name == "Michael"). The syntax and semantics of the different expressions are documented in their respective sections.

2.7Selector

A selector is a subset of an expression used to search for fields inside a document. They have their own evaluation logic (see EvaluateSelector()) which is used by certain functions.

3.1Overview

A GROQ query is executed inside a query context, which contains the dataset and parameters, and returns a result. Typically the result is serialized to JSON. During the execution of a query different parts of the query are evaluated in different scopes. Each scope has a this value and can be nested. Simple attributes like name always refers to an attribute on the this value.

Example № 4*[_type == "person"]{name, friends[country == "NO"]}

In the preceding example we have several scopes:

• The first filter ([_type == "person"]) creates a new scope for every document in the dataset. An equivalent scope is created inside the projection ({name, …}).
• The country filter ([country == "NO"]) creates a new scope for each element in the friends array.

The parent expression (^) let’s you refer to parent scopes, and this enables what is typically solved with joins in many databases.

Example № 5*[_type == "person"]{
  id,
  name,
  "children": *[_type == "person" && parentId == ^.id]
}

While executing the inner filter ([_type == "person" && parentId == ^.id]) the expression ^.id returns the id attribute of the parent scope’s this value. The parent scope is here the scope created by the projection ({id, name, …}).

It’s possible for a query to be invalid. This can happen when you e.g. use an unknown function or call a function with incorrect number of arguments.

3.2Mode

Queries can be executed in two different modes: normal and delta. Delta mode is intended to be used in case where a change has been done to a document. In this mode you have the additional functionality of accessing the attributes before and after the change, and comparing the differences between them (using the functions in the delta-namespace).

3.3Query context

A query context consists of:

• the dataset
• parameter values (map from string to value)
• the mode: either “normal” or “delta”

If the mode is “delta” then the query context also has:

• a before object (which is null if this was a create-operation).
• an after object (which is null if this was a delete-operation).

3.4Scope

A scope consists of:

• a this value
• an optional parent scope
• a query context

A root scope can be constructed from a query context, and a nested scope can be constructed from an existing scope.

3.5Expression validation

An expression can be validated. This will only check that it’s on a valid form, and will not execute anything. If an expression type does not have an explicitly defined validator in this specification, it has an implicit validator which runs Validate on all its child expressions.

3.6Expression evaluation

An expression is evaluated in a scope. You must successfully validate an expression before you attempt to evaluate it. Every expression type has their own evaluator function in their respective section in this specification (e.g. the evaluator of ParenthesisExpression is EvaluateParenthesis()).

3.7Constant expression evaluation

Some expressions can be evaluated into a constant value. This is used for validation and to disambiguate between different syntactically ambiguous expressions.

3.8Score evaluation

When evaluating score, a predicate returning true should have its score computed as 1.0, and all other values should receive a score of 0.0. All results involved in scoring start with a score of 1.0. The scores are evaluated once per result, and then added together. For example:

Example № 6* | score(a > 1)

should assign a score of 2.0 to any document where a > 1, and a score of 1.0 to any non-matching document.

For logical expressions, the score is the sum of the clauses of the expression evaluates to true, otherwise 0.0. In other words:

• true && false receives the score 0.0.
• true && true receives the score 2.0.
• true || true receives the score 2.0.
• true || false receives the score 1.0.

The scoring function for match is left as an implementation detail and not covered by this specification. For example, an implementation may choose to use a TF/IDF or similar text scoring function that uses the text corpus and language configuration for the given field to compute a text score.

A boosted predicate simply adds the boost value to the score if the predicate matches. For example, boost(a > 1, 10) would result in a score of 11 for any expression matching a > 1.

3.9Selector evaluation

A selector (see Selector) is evaluated in a scope with a value and returns a list of key paths. A key path uniquely identifies a value by the attribute names and array indices used to access the value. For instance, the key path .users[1].name refers to the "Bob"-value in {"users":[{"name":"Alice"},{"name":"Bob"}]}.

3.10Traversal execution

When working with JSON values you often need to access attributes in deeply nested arrays/objects. In JavaScript this is solved by using helper functions such as map, filter and flatMap. GROQ provides terse syntax for accomplishing the same functionality.

Example № 7// The following GROQ:
*[_type == "user"]._id

// is equivalent to the following JavaScript:
data.filter(u => u._type == "user").map(u => u._id)

The following expressions are implemented as a traversal:

• user.name: AttributeAccess.
• image->: Dereference.
• users[0]: ElementAccess.
• users[0...5]: Slice.
• users[type == "admin"]: Filter.
• users[]: ArrayPostfix.
• user{name}: Projection.

When these traversals are combined (e.g. user.roles[0].permissions[priority > 2]{filter}) it triggers a separate traversal logic.

Informally the traversal logic is based on a few principles:

• Traversal semantics are always statically known. The runtime value of an expression never impacts the overall interpretation of a traversal.
• We categorize traversals into four types (plain, array, array source, array target) based on how they work on arrays. .user.name is considered a plain traversal because it statically only deals with plain values. [_type == "user"] is considered an array traversal because it works on arrays.
• Placing a plain traversal next to an array traversals ([_type == "user"].name.firstName) will execute the plain traversal for each element of the array.

Formally the semantics are specified as follows:

• Each traversal has a traverse function which describes how it will traverse a value. This function takes a value and a scope as parameters.
• There’s a set of traversal combination functions which specifies how two traversals can be combined. This explains exactly how .user.name is mapped over each element of an array.
• TraversalPlain, TraversalArray, TraversalArraySource, TraversalArrayTarget specifies the exact rules for how multiple traversals are combined together.
• The TraversalExpression node is an Expression for the full set of traversal operators. This kicks off the whole traversal semantics.

3.11Query execution

To execute a query you must first construct a query context, and then evaluate the query expression inside a root scope.

4.1Null

An unknown value, expressed as null. This follows the SQL definition of null, which differs from the typical definition of “no value” in programming languages, and implies among other things that 1 + null yields null (1 plus an unknown number yields an unknown number).

4.2Boolean

Logical truth values, i.e. true and false.

4.3Number

Signed 64-bit double-precision floating point numbers, e.g. 3.14, following the IEEE 754 standard. These have a magnitude of roughly 10⁻³⁰⁷ to 10³⁰⁸, and can represent 15 significant figures with exact precision – beyond this, significant figures are rounded to 53-bit precision. The special IEEE 754 values of Infinity and NaN are not supported, and are coerced to null.

4.4String

A string stores an UTF-8 encoded list of characters.

The syntax of a string literal is a subset of JSON with the following extensions:

• Any control characters (including newlines) are allowed to appear inside a string.
• Extended support for referring to Unicode characters above 16-bit: "\u{1F600}".

Escape sequences are interpreted as follows:

• \' represents U+0027.
• \" represents U+0022.
• \\ represents U+005C.
• \/ represents U+002F.
• \b represents U+0008.
• \f represents U+000C.
• \n represents U+000A.
• \r represents U+000D.
• \t represents U+0009.
• \uXXXX represents the Unicode code point U+XXXX.
• \uXXXX\uYYYY, where XXXX is a high surrogate (W1, 0xD800–0xDBFF) and YYYY is a low surrogate (W2, 0xDC00–0xDFFF) is interpreted as a UTF-16 surrogate pair and encoded into a single code point.

It’s a syntactical error when a Unicode escape sequence represents an invalid Unicode code point.

4.5Array

An ordered collection of values, e.g. [1, 2, 3]. Can contain any combination of other types, including other arrays and mixed types. An element inside an array literal can be preceded by ... which causes it to be flattened into the array.

4.6Object

An unordered collection of key/value pairs (referred to as attributes) with unique keys, e.g. {"a": 1, "b": 2}. Keys must be strings, while values can be any combination of other types, including other objects. If duplicate keys are specified, the last key is used.

The values of an object literal can use the full power of expressions:

Example № 8*[_type == "rect"]{"area": width * height}

Object literal supports syntactical sugar when the attribute name and value is equivalent:

Example № 9// These two are equivalent
*[_type == "person"]{name}
*[_type == "person"]{"name": name}

4.7Pair

A pair of values, e.g. "a" => 1. Pairs can contain any combination of other types, including other pairs, and are mainly used internally with e.g. projection conditionals andselect().

In serialized JSON, pairs are represented as a string on the form fst => snd where fst and snd are the serialized JSON for the first and the second expression.

4.8Range

An interval containing all values that are ordered between the start and end values. The starting value is always included, while the end may be either included or excluded. A right-inclusive range is expressed as two values separated by .., e.g. 1..3, while a right-exclusive range is separated by ..., e.g. 1...3.

Ranges can have endpoints of any comparable data type, but both endpoints must be of the same type (except integers and floats which can be used interchangeably). Ranges with incompatible or invalid endpoints types will yield null.

Ranges are mainly used internally, e.g. with the in operator and array slice access operator. The endpoints may have context-dependent semantics, e.g. in array slices the range [2..-1] will cover the range from the third array element to the last element, while the same range is considered empty when used with in. For more details, see the documentation for the relevant operators.

In serialized JSON, ranges are represented as a string on the form start..end (for inclusive ranges) and start...end (for exclusive ranges) where start and end are the serialized JSON for the start and the end expression.

4.9Datetime

A datetime is a combination of a Gregorian-calendar date and a time in UTC. It’s stored in millisecond precision, but an implementation can choose to support even finer granularity. Datetimes support date/time arithmetic. Only valid date/time combinations can be represented.

Datetimes cannot be constructed from literals, but must be constructed with the dateTime function.

In serialized JSON, datetimes are represented as a string with using RFC 3339 timestamp format, e.g. 2006-01-02T15:04:05Z using the following rules:

1. If there is no millisecond information in the datetime, format it without any fractional digits: 2006-01-02T15:04:05Z
2. If there is millisecond information in the datetime, format it with 3 fractional digits: 2006-01-02T15:04:05.508Z
3. If the datetime contains even finer granularity, it’s implementation dependent how the additional fractional digits are formatted.

5.1Equality

Simple values such as numbers, strings, booleans and null are equal when they contain the same data. All other values are considered inequal to each other (e.g. [] != []).

5.2Partial comparison

A partial comparison between two values return either Greater, Equal, Less or null. null represents that the values are incomparable to each other. This is used by the comparison operators (<, ≤, >, ≥).

5.3Total comparison

A total comparison between two values return either Greater, Equal or Less. It provides a consistent ordering of values of different types (for string, numbers and boolean) and considers all other types to be equal to each other. This is used by the order() function.

6.1This expression

A this expression returns the this value of the current scope.

Example № 10*[_id == "doc"][0].numbers[@ >= 10]
                           ~

6.2This attribute expression

A this attribute expression returns an attribute from the this value of the current scope.

Example № 11*[_id == "document"][name == "Michael Bluth"]
  ~~~                ~~~~

6.3Everything expression

An everything expression returns the full dataset.

Example № 12*[_type == "person"]
~

6.4Parent expression

A parent expression returns a this value for an upper scope.

Example № 13// Find all people who have a cool friend
*[_type == "person" && *[_id == ^.friend._ref][0].isCool]
                                ~

6.5Function call expression

GROQ comes with a set of built-in functions which provides additional features. See the “Functions” for available functions and their namespaces.

Example № 14*{"score": round(score, 2)}
           ~~~~~~~~~~~~~~~

*{"description": global::lower(description)}
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

7.1Parenthesis expression

A parenthesis expression allows you to add parenthesis around another expression to control precedence of operators.

Example № 15(1 + 2) * 3
~~~~~~~

7.2Traversal expression

A traversal expressions starts a traversal.

Example № 16users.foo.bar[0].sources[]->name

When the left-hand side is an Everything, Array, or PipeFuncCall this is interpreted as if there was an additional explicit ArrayPostfix traversal. E.g. *._id is interpreted as *[]._id and therefore returns an array of IDs.

7.3Pipe function call expression

GROQ comes with a set of built-in pipe functions which provides additional features. Pipe functions always accepts an array on the left-hand side and returns another array, and the syntax is optimized for being able to chain it together with other compound expressions. See the “Pipe functions” for available functions.

Example № 17*[_type == "person"] | order(name) | {age}
                     ~~~~~~~~~~~~~

8.1Attribute access traversal

An attribute access returns an attribute of an object.

Example № 18person.name
      ~~~~~

person["Full Name"]
      ~~~~~~~~~~~~~

8.2Element access traversal

An element access returns an element stored in an array. The array is 0-indexed and a negative index accesses the array from the end (i.e. an index of -1 returns the last element; -2 refers to the second last element).

8.3Slice traversal

A slice returns a slice of an array.

Example № 19people[0..10]
      ~~~~~~~

8.4Filter traversal

A filter returns an array filtered another expression.

Example № 20*[_type == "person"]
 ~~~~~~~~~~~~~~~~~~~

8.5Array postfix traversal

An array postfix coerces the value into an array.

8.6Projection traversal

A projection operator returns a new object.

Example № 21*[_type == "person"]{name, "isLegal": age >= 18}
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

8.7Dereference traversal

8.8Disambiguating square bracket traversal

Filter, ElementAccess and AttributeAccess are syntactically ambiguous, and the following algorithm is used to disambiguate between them.

9.1And operator

9.2Or operator

9.3Not operator

9.4Equality operators

9.5Comparison operators

9.6In operator

9.7Match operator

The match operator is defined in terms of patterns and tokens: It returns true when any of patterns matches all of the tokens. The exact way of tokenizing text and interpreting patterns is left as an implementation detail.

9.8Asc operator

The asc operator is used by the order() function to signal that you want ascending sorting. Evaluating it in any other context is not allowed.

9.9Desc operator

The desc operator is used by the order() function to signal that you want descending sorting. Evaluating it in any other context is not allowed.

9.10Unary plus operator

9.11Unary minus operator

9.12Binary plus operator

9.13Binary minus operator

9.14Binary star operator

9.15Binary slash operator

9.16Binary percent operator

9.17Binary double star operator

11.1Global namespace

Example № 22* | score(boost(title matches "milk", 5.0), body matches "milk")

11.2Date/time namespace

The dateTime namespace contains functions to work with datetimes.

11.3Diff namespace

The diff namespace contains functionality for comparing objects.

11.4Delta namespace

The delta namespace contains functions which are valid in delta mode.

12.1global::order()

The order function sorts an array based on arbitrary expressions.

12.2global::score()

The score function assigns a score to an array of results, based on one or more scoring expressions. The score function may only be used as a pipe function.

Example № 24*[_type == "listing"] | score(body match "jacuzzi")

In this query, anything where body match "jacuzzi" returns true will be scored higher than other results. Multiple expressions can be used:

Example № 25*[_type == "listing"] | score(body match "jacuzzi", bedrooms > 2, available && !inContract)

When multiple expressions are provided, the scores are merged into a single score for each result (see score evaluation)

Only predicate expressions — that is, expressions that evaluate to a single boolean value or to null — may be used, including boost(). However, an implementation can put further constraints on which expressions are permitted as a score expression for optimization purposes.

Each score is assigned to the result as the new attribute _score, set to a positive number.

Scoring is additive. That is * | score(a == 1) | score(b == 2) is equivalent to * | score(a == 1, b == 2).

13.1global::identity()

The identity function should accept zero arguments and return a string which represents the identity of the client executing the query.

13.2global::path()

The path function should accept a single argument and return a path object.

14.1Portable Text Extension

Functions available in Portable text extension are grouped under pt namespace except for the constructor which is global.

14.2Geography Extension

Functions available in Geography extension are grouped under geo namespace except for the constructor which is global.