Functions

// Query
fn ex::info($person) = $person{name, age}; 
*[_type == "person"] { "info": ex::info(@) }

• Get started with custom functions.
• View the reference documentation.
• See the updated GROQ language spec.

This release introduces new features and changes to support Content Releases. For more details on Content Releases, see the Studio release notes.

The following items may break behavior in your applications. See the details below for further explanations and migration paths.

• The default perspective has changed to only display published content.
• Raw perspective requests now include versions. prefixed documents in addition to drafts. and published documents.
• A bug in GROQ queries that caused empty keys to expand has been fixed. If you are relying on this behavior, see the details below.

versions.** documents are not returned in API versions prior to 2025-02-19. You must opt-in to this version to query versions-prefixed documents.

The default perspective has changed from raw to published. This includes:

• /query now uses perspective=published by default.
• GraphQL now uses perspective=published by default.

To return to the previous behavior, set perspective to raw.

In addition to the existing named perspective values, you can also pass one or more release IDs to the query endpoint's perspective parameter. For example: perspective=release-a,release-b,release-c. This will give you a view on your dataset as if release-c had been published, followed by release-b and finally release-a. This is generalisation of the existing previewDrafts functionality to support Content Releases.

Learn more in the Content Releases API documentation.

The following endpoints now include a boolean includeAllVersions parameter. Set it to true and use an authenticated request to include all versions.

• /listen
• /doc

Prior to 2025-02-19, queries on /query and similar APIs returned published documents and drafts.** documents when using the raw or previewDrafts perspectives. In 2025-02-19 and later, a versions.** path is introduced for Content Release document versions.

If you rely on path prefixes alone, you'll want to use perspectives instead to control which documents are returned by queries.

The Actions API now includes actions for managing Content Releases. Along with this, actions such as sanity.action.document.discard and sanity.action.document.replaceDraft have been deprecated in favor of sanity.action.document.version.discard and sanity.action.document.version.replace.

See the Actions API reference for more details.

• sanity::versionOf(documentID): Checks for versions of a provided document ID. Use inside a filter to return matching documents. For example: *[sanity::versionOf("abc123")].
• sanity::partOfRelease(releaseID): Checks whether a document is part of a given release. For example, fetch all the version documents in release rel-summer using *[sanity::partOfReleases("rel-summer").
• releases::all(): Returns all releases.

Learn more about these in the GROQ functions reference documentation.

The document history API now accepts a lastRevision parameter, which returns the current data for an existing document, or the last state before deletion for a deleted document.

This version also introduces a fix to a GROQ bug whereby empty keys in projections would expand into the object.

For example:

Input

{
  "": {
    "a": "b"
  }
}

response

{
  "a": "b"
}

This is corrected in 2025-02-19, and instead the query will return the following:

{
  "": {
    "a": "b"
  }
}

To replicate the older behavior in the new API version, update the empty string with the ellipsis operator (...). For example:

{
  ... {
    "a": "b"
  }
}

The array::intersects() function for GROQ, previously available in experimental releases, is now fully stable and compatible with all dated API versions. You can now use this function in webhook filters, permission filters, and with groq-js, allowing for more flexible array operations across different contexts.

There are three new namespaces for functions added to the specification, which have been implemented across all GROQ tooling. These are:

array:: functions: Perform array operations on lists, such as removing all null values, building text strings from a list of names, or generating a list of all unique document _types.

• array::compact(<array>) - removes all null values from an array
• array::join(<array>, <token>) - concatenates all array elements into one string, separated by a specified token.
• array::unique(<array>) - removes duplicate values from an array (this works for values that can be compared for equality, specifically numbers, strings, booleans, and null, and will not work for values that are arrays or objects)

math:: functions: Run common mathematical operators on numeric values. For example, you can add the prices across multiple products or return the maximum discount available within a cart of products.

• math::avg(<array-of-numbers>) - calculates the average value (arithmetic mean) of an array of numbers.
• math::max(<array-of-numbers>) - returns the largest numeric value of an array of numbers.
• math::min(<array-of-numbers>) - returns the smallest numeric value of an array of numbers.
• math::sum(<array-of-numbers>) - calculates the sum of an array of numbers.

string:: functions: Manipulate text or validate that information matches a given prefix. For example, get a list of the articles that start with “How to” or split a comma-separated string of author names into an array.

• string::split(<string>, <delimiter-token>) - turns a string into an array of substrings based on a delimiting token.
• string::startsWith(<string>, <string-pattern>) - checks if a prefix string exactly matches the start of another string.

To learn all about the new GROQ functions, read the developer update accompanying this release, and visit our documentation.

With this release, we are also pleased to announce the formal language specification of GROQ, as well as a new versioning scheme. Taking inspiration from other well-known language specs, like HTML and SQL, we settled on the following format:

GROQ-<major version #>.revision<#>

The current version of the specification is GROQ-1.revision1. This version does not include any breaking changes. To learn more about the history and future of the GROQ language, read the blog post from Co-founder and CTO Simen Svale Skogsrud: Content is Queryable: (Re)Introducing GROQ.

Content Lake is a full refactor of Sanity's backend and query engine. You can start using it by upgrading and specifying an API version for your client. Content Lake follows the GROQ specification and introduces both bug fixes and new features.

We have updated the documentation to reflect the newest version. This changelog contains the breaking changes and migration paths you need to take. You can take your time and stay on v1 for as long as you need, while you test and compare your queries against the new version. You can also specify the API version for only new queries to gradually move over. Let us know in the community if you have questions or need help.

The GROQ ^ operator now works correctly in all scopes.

This fixes the known issue where the ^ operator only worked in subqueries. In all other scopes, it returned the root of the current scope, instead of the parent scope.

*[_type=="person"]{
  name,
  someObj{
    name,
    // Old Behavior: "parentName" returns someObj.name
    // New Behavior: "parentName" returns root name value
    "parentName": ^.name
  }
}

GROQ now uses three-valued logic consistently:

• >, >=, <, <= returns null when the operands are of different types.
• &&, || handles null "as expected": null && true ⇒ null and null || true ⇒ true.

Note that == has changed slightly:

• It now always return either true or false (never null).
• You can compare against null and get the expected result: 123 == null ⇒ false and null == null ⇒ true.
• Comparisons between other types than strings/booleans/numbers always return false.

This also means that in works with null: null in foo will return true if foo is [null, 1, 2].

in null always returns null.

We have cleaned up the behavior for array traversal. For example, queries that contained multiple array traversals that don't work in v1, now work as expected in v2021-03-25 and onward.

*["link" in body[].markDefs[]._type]
// v1: No results
// v2021-03-25: An array of documents that has a link annotation in their "body" field

// Data:
[
  {
    "_type": "book",
    "authors": [
      { "names": ["MH", "Holm"] },
      { "names": ["Bob"] },
    ]
  }
]

// Query:
*[_type == "book"].authors[].names

// v1:
[null]

// v2021-03-25:
[
  [
    "MH",
    "Holm",
  ],
  [
    "Bob"
  ]
]

// You can also add an additional `[]` to flatten it completely:

// Query:
*[_type == "book"].authors[].names[]

// v2021-03-25:
[
  "MH",
  "Holm",
  "Bob"
]

If you have stored null values in your documents, these are no longer removed in projections.

You can now override attributes while using the spread operator (...).

// Data
[{"title": "A", "customTitle": "B", "_type": "post"}]

// Query:
*[_type == "post"]{..., "title": customTitle}

// Output from v1: 
[{"title": "A"}]

// Output from v2021-03-25:
[{"title": "B"}]

All numbers are now 64-bit floats. Previously we used 64-bit integer representation in certain contexts.

Previously ordering by strings would in some context use a "smart" numeric ordering instead of proper string comparison:

// Query:
["foo4", "foo12"]|order(@)

// v1:
["foo4", "foo12"]

// v2021-03-25:
["foo12", "foo4"]

// However, *|order(foo) has always (both before and after) used proper string comparison.

The is operator has been deprecated. You can use the equivalent comparison instead:

// v1:
*[_type is "post"]

// v2021-03-25:
*[_type == "post"]

Previously you could call functions without parentheses: *[length "foo" > 3]. This is now no longer possible and is a syntax error. You should use *[length(foo) > 3] instead.

You can use now() and identity() instead.

Whenever you apply the projection operator ({}) on a non-object then it returns null instead of executing the object expression.

This means that the following query *[foo == bar][0]{a} now correctly returns null if there were no results. Previously this returned {}.

Previously negative indexes were not respected: [_type == "article"][-1] was equivalent to [_type == "article"][1]. This has now been fixed and -1 returns the last document.

The following query now fails: *[_type == "bar" && @[""] == "bar"] since empty attribute keys are not allowed.

Passing | order(…) on non-arrays return a null value instead of converting it to an array.

defined(x) is now only false when x is null. Previously it was false for empty arrays and objects as well.

The pipe operator (|) used to work between nearly all access operators, filters, and slices (e.g., * | [filter], * | (foo), * | [2..4], and * | [2] were all permitted). The pipe operator remains required before the score() and order() pipe functions, and is optional before a projection, but using one before a filter or traversal syntax will throw an error.

Namespaces allow for a stronger grouping of functionality within the GROQ specification. They create dedicated spaces for global functions, as well as safer distinctions for specific implementations of GROQ. Learn more.

The score() function computes a _score for each document from how well the expression matches the document. The documents will also be sorted by score (from high to low) if no other order() function is specified. Note that all documents will be scored (even those that don't match it at all) so you typically want to add a limit. Read more about scoring and boosting.

The pt::text() function takes either a Portable Text block or an array of blocks and returns a string in which blocks are appended with a double newline character (\n\n). Text spans within a block are appended without space or newline. Read more about getting plain text from Portable Text.

The geo namespace contains a number of useful functions for creating and querying against locations in your data. Query for distance, intersections, and more.

It's now possible to filter and order efficiently on date times:

// Filter
*[_type == "post" && dateTime(publishedAt) > dateTime("2021-01-01T12:00:00")]

// Order
*[_type == "post"]|order(dateTime(publishedAt) desc)

If you have huge documents, but your queries have projections that filter away most of the data (e.g., *[_type == "post"]{title, description}) you may see performance improvements.

Expressions that use both && and || will now often be much faster (depending on how complicated they are).

*[
  _type == "post" &&
  slug == "hello" &&
  ("news" in tags || products[0].name == "Sanity")
]

// v1: Slow!
// v2021-03-25: Much faster!