Content is Queryable: (Re)Introducing GROQ

Today, we’re pleased to announce that GROQ, our open-source query language for content, is formalized as a working language specification. Teams can now more confidently rely on support for the language and associated tooling as a critical aspect of Sanity. If you use Sanity and GROQ today, be sure to check out this post outlining the thinking behind the GROQ language specification versioning, as well as an overview of new functions introduced to GROQ and our tooling.

We invented GROQ because we realized most so-called "Content APIs" out there were poorly executed. Even today, most CMSes tend to design content APIs around outdated website patterns, making it hard for content teams to deliver remarkable and sustainable digital experiences. At Sanity, we believe content should be treated as data. GROQ is an example of this. It lets you query any collection of JSON documents and filter them down to exactly what you need by their properties and value. And it lets you reshape and reform that data, using projections and functions.

It was never the goal to invent a new query language for content. But our team didn’t find an API pattern that met the criteria for making it easy to query connected content in JSON documents freely. We believe developers should be able to combine and reshape content to fit an evolving, creative set of experiences. And to do so without having content creators regularly re-author existing content for new uses, like creative ideas for more immersive newspaper stories, or more expressive and varied product pages in online stores. Awesome ideas are often dialed back due to so-called practical technical limitations. We all deserve better.

GROQ provides unprecedented freedom in how you power content-driven experiences. Developers can rapidly produce digital experiences for any channel, thanks to the more flexible design approach GROQ provides when working with structured content. We have seen countless projects where GROQ improves code readability, saves development time, and provides powerful functions for combining, transforming, and retrieving content for a wide variety of use cases.

We avoid proprietary standards and vendor lock-in wherever we can, so GROQ has been a documented, open-source language for years. We also open-sourced our parser compiler, Glush. We have been humbled to see the response from the developer community, including the creation of guides, courses, sample code, and plugins to work with GROQ. All of these materials have helped with its adoption in the wider content ecosystem.

GROQ has been available on GitHub as a working draft for a couple of years while we’ve worked with our customers and community to learn how they use it. Taking these learnings, we have formalized a versioning scheme to conform the GROQ implementation in the Content Lake API version with other GROQ tooling, such as the JavaScript library groq-js. If you’re into language specifications, find the latest revision of the GROQ spec and future updates here.

In addition to GROQ’s new spec release structure, we’ve introduced new functions for developers. For example, as defined in GROQ-1.revision1, developers can now use new array functions to find distinct values and remove null values, string functions, and math functions like sum() to rapidly compute against content. To learn more and see an example, check out this technical blog post on GROQ’s new features. All of these features were prioritized thanks to feedback from our community.

Existing Sanity customers can use these new GROQ features with their content on Content Lake API version v2022-03-13 and v2021-10-21. If you are new to Sanity and want to experience a modern CMS that treats content as data, get started here.