Functions take a set of arguments of specific types and return a single value of a specific type. They may be polymorphic, i.e. accept several argument type variations possibly returning different types, and may take a variable number of arguments. Function calls return
null if arguments have invalid types, and an error if the function does not exist.
Functions may throw errors rather than return
null on type conflicts.
Takes a variable number of arguments of any type, and returns the first non-
null argument if any, otherwise
null - e.g.
coalesce(null, 1, "a") returns
Returns the number of elements in the passed array, e.g.
Accepts a string on the RFC3339 format and returns a DateTime (the format used in the
_updatedAt fields). Typically used to let GROQ know to treat a string as a date, especially useful when you need to compare them or perform time arithmetic operations.
Subtracting two DateTimes returns the number of seconds between those time stamps. Adding a number to a date time returns the date time that amount of seconds later (or earlier if the number is negative).
true if the argument is non-
null and not an empty array or object, otherwise
Returns the identity (user ID) of the user performing the current action, or the special values
<anonymous> for unauthenticated users and
<system> for system-initiated actions.
Returns the length of the argument, either the number of elements in an array or the number of Unicode characters in a string, e.g.
length("Hi! 👋") returns
Returns the current time in ISO 8601-format with microsecond resolution in the UTC time zone, e.g.
2019-03-06T15:51:24.846513Z. The current time is stable within an operation such that multiple calls return identical values, and this generally refers to the start time of the operation except for listener queries which refer to the event's transaction time.
query parameters triggers two separate operations internally: first execution of queries to determine which documents to update, then a transaction to actually update the documents.
now() will return different times for these two operations, referring to the start time of each operation.
Coerces the passed string to a path, e.g.
"a.b" in path("a.*").
Implicitly takes the document at the root of the current scope and recursively checks whether it contains any references to the given document ID(s). It is typically used in query filters, e.g.
*[ references("abc") ] will return any documents that contains a reference to the document
abc. If providing the function with an array of document ids, it will return
true if any of the ids are referenced.
round(<integer|float>[, <integer>]) <integer|float>
Rounds the given number to the nearest integer, or to the number of decimal places given by the second, optional argument - e.g.
round(3.14, 1) yields
Used for conditionals, i.e. "if-else" expressions. Takes a variable number of arguments that are either pairs or any other type and iterates over them. When encountering a pair whose left-hand value evaluates to
true, the right-hand value is returned immediately. When encountering a non-pair argument, that argument is returned immediately. Falls back to returning
For example, the following call returns
age >= 18, otherwise
age >= 13, otherwise
select( age >= 18 => "adult", age >= 13 => "teen", "child" )