GROQ for People Who Know SQL

GROQ is the query language you use to pull content out of Sanity. If you know SQL, you’ll be productive in an afternoon, the concepts map closely. It’s the handful of places they diverge that cause the head-scratching, so let’s start there.

The mental model

A GROQ query filters a single collection of all documents, then shapes the result. Where SQL says “SELECT columns FROM table WHERE condition,” GROQ says “filter the documents, then project the fields.” There are no tables, everything lives in one dataset, and you filter by document type instead of choosing a table.

Filtering

The filter is written in square brackets: the equivalent of a WHERE clause. You almost always filter by _type first, that’s your “FROM table”, then add conditions. It reads left to right: first narrow the documents, then decide what to return.

Projection

The projection, in curly braces, is your SELECT list. You name the fields you want, rename them, compute new ones, and, this is the part SQL people love, follow references inline. Instead of a JOIN, you dereference a linked document right inside the projection and pull its fields into the shape you’re building.

The differences that trip people up

Three things. Joins are replaced by dereferencing, which is simpler once it clicks. There’s no schema-enforced structure at query time, you’re querying a document store, so defensive projections help. And ordering and slicing use their own syntax rather than ORDER BY and LIMIT, though the idea is identical.

Why it matters for hosting

GROQ runs against Sanity’s hosted API, so your queries don’t need a database of your own. Your front end just needs somewhere to run, for a Next.js site, a Node host. That’s the piece we cover at /sanity.

The bottom line

GROQ isn’t a new paradigm to learn from scratch, it’s SQL’s ideas rearranged for a document store, with dereferencing in place of joins. Lean on what you know from SQL and adjust for those few differences. More on the stack at /sanity.