Index
Edit

Data Types

GROQ is strongly typed, meaning there is no implicit type conversion. Type conflicts (e.g. 1 + "a") will yield null.

Known issue

Although type conflicts should yield null, in many situations they yield false or an error instead.

For more information on how to express literal values for various datatypes, see the Syntax section.

Basic Data Types

Boolean

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

Float

Signed 64-bit double-precision floating point numbers, e.g. 3.14, using the IEEE 754 binary64 format. 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 (not a number) are not supported, and are coerced to null.

Integer

Signed 64-bit integers, e.g. 42, with a range of -2⁶³ to 2⁶³-1.

Known issue

Integers in stored documents are currently rounded to 53-bit significand precision.

Null

An unknown value, expressed as null. This is 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). See the Operators section for further implications of this.

String

A UTF-8 encoded string of characters, e.g. "Hi! 👋". The maximum string length is undefined, but is fundamentally limited by the maximum document size and maximum HTTP request size as listed in Technical Limits.

Composite Data Types

Array

An ordered collection of values, e.g. [1, 2, 3]. Can contain any combination of other types, including other arrays.

Object

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.

Pair

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 and select(). In returned JSON, pairs are represented as arrays with two values.

Range

An interval containing all values that are ordered between the start and end values (for details on ordering, see "Comparison operators" in the Operators section). 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 basic 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.

Known issue

Ranges currently may not work with all ordered types, and endpoint type conflicts may be handled incorrectly. Ranges also cannot be expressed in returned JSON.

Ranges are mainly used internally, e.g. with the in operator and array slice access operator. The endpoints may have context-dependant 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.

Subtypes

Subtypes are subsets of basic or composite types. Operators and functions that can act on the supertype can always act on the subtype as well, but the behavior may be modified, and some operators and functions can only act on the subtype.

Datetime

Datetimes are strings with ISO 8601-formatted date/time combinations, e.g. 2018-11-04T13:45:21Z.

Known issue

Datetimes are currently treated as plain strings, so e.g. comparisons will not take the time zone into account.

Document

Documents are objects which contain the following special attributes (in addition to other arbitrary attributes):

  • _id (path, required): The unique ID of the document. IDs must begin with the characters a-zA-Z0-9_, followed by any of the characters a-zA-Z0-9_.-, and end with a-zA-Z0-9_-. IDs can have a maximum length of 128 characters, and may not contain more than a single consecutive . character.
  • _type (string, required): An arbitrary document type. Types may not be longer than 255 characters, may not contain , or #, and may not begin with . or _.
  • _rev (string): A randomly generated revision ID corresponding the the transaction ID which generated this revision.
  • _createdAt (datetime): The time when the document was originally created.
  • _updatedAt (datetime): The time when the document was last modified.

Path

Paths are strings that represent a node or branch in a tree (i.e. hierarchy). They are typically used for document IDs, where each path segment is separated by ., e.g. articles.business.finance.4861.

Paths can also be glob patterns, using * wildcards which do not cross . and ** wildcards which do cross .. For example, the path articles.business.finance.4861 is matched by the path articles.business.**, but not articles.business.*.

Paths are most commonly used in conjunction with the in operator when filtering documents, e.g. _id in path("articles.business.**").

Reference

References are objects that represent a reference to a different document. They have the following special attributes (in addition to other arbitrary attributes):

  • _ref (path, required): The ID of the referenced document.
  • _weak (boolean): If true, referential integrity is not enforced, i.e. the reference is allowed to point to a non-existent document. Defaults to false.

Previous: SyntaxNext: Variables