Index
Edit

Variables

GROQ variables are predefined and can not be set by users (see "Parameters" below for user-defined parameters). For example, in the document filter [ name == "someName" ] the variable name has been set to the value of the current document's name attribute. Variables can contain values of any type, and undefined variables evaluate to null.

For information on valid variable names, see "Identifiers" in the Syntax section.

Pro-tip

JSON documents allow attribute names to be any arbitrary UTF-8 string. In cases where these names are not valid GROQ identifiers, they can instead be accessed by using the special variable @ (typically referring to the current document) and the [] attribute access operator, e.g. @["1 illegal name 🚫"].

Variable Scope

Variables are scoped, such that the same name may refer to different values in different contexts. New scopes are created by pipeline components, where the component expression is evaluated in the scope of the currently processed value. For example, in the query *[ price + tax > 10 ] the variables price and tax are set by the filter component to the corresponding attribute values of each document passed from *.

Scopes can be nested, in which case the ^ variable can be used to refer to variables in the parent scope. For example, consider the following query:

*[ _type == "movie" && releaseYear >= 2000 ]{
  title,
  releaseYear,
  "crew": crew{name, title, birthYear},
  "related": *[ _type == "movie" && genre == ^.genre ]
}

In the filter, _type and releaseYear refer to the corresponding attributes of each document passed from *. Similarly, in the projection, title, releaseYear, and crew refer to the attributes from each document. However, in the nested crew projection the variables name, title, and birthYear refer to the attributes of each object passed from the crew array - notice how the outer and inner title variables are not the same (one is from the movie, the other from the crew member), as they are evaluated in different scopes.

The related subquery components also create new scopes, where the _type and genre variables are set to the attributes of the document fetched from the preceding *, not those of the original projected document. Notice how the special variable ^ is used to refer to attributes from the parent (outer) scope.

Special Variables

*: Everything

Returns an array of all stored documents that the current user has access to. It is typically used at the beginning of a GROQ query pipeline, such as *[ _type == "movie" ]{ title, releaseYear }.

@: This

Returns the root value of the current scope, or null if no root value exists. For example, in the document filter [ @.attribute == "value" ] it refers to the currently filtered document, and in the expression strings{"string": @, "length": length(@)} it refers to the currently processed string of the strings array.

^: Parent

Returns the root value of the parent scope, or null if no parent scope exists. For example, in the following query it refers to the projected document, not the document passed from the inner *:

*{ "referencedBy": *[ references(^._id) ]}
Known issue

The ^ variable currently only works from subqueries. In all other scopes, it returns the root of the current scope, not the parent scope. It is also not possible to chain ^ to refer to grandparent scopes.

Parameters

Parameters are client-provided values that are substituted into queries before execution. Their names must begin with $ followed by a valid identifier, and their values must be JSON literals of any type (take care to quote strings). Since they are JSON literals they can only contain values, not arbitrary GROQ expressions, and are safe to pass from user input.

For example, the following query may be given parameters such as $type="myType" and $object={"title": "myTitle", "value": 3}:

*[ _type == $type && title == $object.title && value > $object.value ]

In the HTTP API, parameters are passed via URL query parameters, see the HTTP API documentation for details.

Predefined Parameters

The following parameters are predefined and available for use in all GROQ queries:

  • $identity (string): The ID of the current user, or <anonymous> for unauthenticated users.
  • $now (datetime): The current server time.

Previous: Data TypesNext: Operators