Part of frameworks/sanity. [reference]
Real code: munakalati — 24 queries against 434 posts · Compare: SQL reference
Every query has the same three parts
*[ filter ] | order(...) [slice] { projection }*[_type == "post" && defined(publishedAt) && publishedAt <= now()]
| order(publishedAt desc)
[0...20]
{ _id, title, slug, excerpt, publishedAt,
coverImage { asset, alt },
author-> { name, photo, role } }*— every document in the dataset. There are no tables; one flat pool.[...]— the filter._type == "post"is the nearest thing to aFROM, and it’s just a predicate.| order()and[0...20]— sort and slice. The range is end-exclusive, three dots. A second[...]after a filter is a slice, not another filter.{...}— the projection. What comes back. This is where performance lives.
Translating from SQL
| SQL | GROQ |
|---|---|
SELECT a, b | trailing { a, b } |
FROM posts | *[_type == "post"] |
WHERE x = $y | the same [...], ANDed |
ORDER BY d DESC | | order(d desc) |
LIMIT 20 | [0...20] |
OFFSET 40 LIMIT 20 | [40...60] |
JOIN authors ON … | author-> |
COUNT(*) | count(*[…]) |
IS NOT NULL | defined(x) |
NOW() | now() |
The difference that matters: the projection is a shape, not a column list. coverImage { asset, alt } returns a nested object with those two keys. You describe the JSON you want back, and it nests arbitrarily. No join tables, no result flattening, no second query.
-> is the entire join story
author-> { name, photo, role }A reference field stores {_type: "reference", _ref: "author-xyz"}. -> follows it and inlines the target document; the {...} then projects fields off it. It chains — author->photo.asset->url is two hops returning one string — and every hop runs server-side in one request, which is exactly what a hand-rolled REST client can’t do without over-fetching or a second round trip.
Renaming and flattening uses a quoted key with an expression:
*[_type == "post" && defined(slug.current)]{ "slug": slug.current }That turns {slug: {current: "x"}} into {slug: "x"} — the caller gets exactly the shape it wants, and nothing else travels.
Parameters, not interpolation
*[_type == "post" && slug.current == $slug][0] { … }client.fetch(query, { slug })$slug is bound, sent alongside the query text, never spliced into it — the same protection a prepared statement gives in SQL. A value containing "] || *[_type == "user" is data, not syntax.
Never build a GROQ string by interpolating user input. It’s especially tempting because the queries already live inside JS template literals.
The groq tag (groq`…`) does nothing at runtime — it returns the string unchanged. Its value is tooling: editor highlighting, and TypeGen finds queries by looking for it. Free to add; the prerequisite for generated types.
[0] — one thing or a list
*[_type == "post" && slug.current == $slug][0] { … } // → object, or null
*[_type == "post" && category == $category] { … } // → array, possibly emptyAlways [0] when you want one, then null-check. Without it you get a one-element array, every field access is undefined, and the page renders blanks instead of a 404.
Note the asymmetry when handling results: a single-document query returns null when it misses, but a list query returns [], never null — and [] ?? fallback gives you [], because an empty array is truthy. Use .length > 0, not ||.
Conditional filters without a dynamic query
*[_type == "post" && ($category == "all" || category == $category)]
| order(publishedAt desc) [$start...$end] { … }One static query serving both “everything” and “one category”. Passing "all" makes the left side true and the clause a no-op.
Why this beats concatenating a filter fragment: the query text stays constant (so it’s cacheable and plan-reusable), and it doesn’t reintroduce the injection surface parameters exist to remove. Slices take parameters too — [$start...$end] is what makes real pagination possible.
count() and the two-query pagination shape
GROQ has no window functions, so a paginated list needs the page and the total as separate queries:
count(*[_type == "post" && ($category == "all" || category == $category)])const [posts, total] = await Promise.all([
client.fetch(pagedQuery, { category, start, end }),
client.fetch(countQuery, { category }),
]);Fire them together. Sequential awaits on independent queries is the most common performance bug in server-rendered data fetching, and nothing about the code looks wrong.
The trap this creates: the filter is now written twice and must stay identical, or the page count won’t match the pages. Change one, get a phantom empty last page.
One query, many keys
A top-level object projection runs several queries in one request:
{
"hero": *[_type == "heroContent" && _id == "heroContent"][0]{ … },
"stats": *[_type == "stat" && context == "home"] | order(order asc){ … },
"testimonials": *[_type == "testimonial"] | order(order asc){ … }
}The answer to a page whose every section fetches its own data. Colocated per-component fetching is more modular; this is one round trip. Which wins depends entirely on whether the page is cached — under ISR, several fetches per hour is nothing; on a dynamic page it’s the whole latency budget.
defined(), now() and defending against your own data
defined(x)— the field exists and isn’t null. Necessary becauserequired()in a schema is a Studio form check, so anything written by a script or a migration can violate it → 01.now()— server-side current time.publishedAt <= now()is scheduled publishing for free: set a future date and the document is invisible until it isn’t. No cron, no publish job. The catch is that it composes with your page cache — under a 60-second revalidate, a scheduled post appears up to a minute late.match— wildcard text matching._id match "wix-*"scopes a destructive script to migrated documents only.
The projection is the optimisation
The highest-value habit in GROQ, and the one people miss because they’re used to SELECT * being fine:
// before: fetches 20 complete posts — body, images, author — to read 20 slugs
*[_type == "post" …] | order(publishedAt desc) [0...20] { _id, title, slug, excerpt, body, coverImage{…}, author->{…} }
// after: the same filter, ~40 bytes per document, no cap
*[_type == "post" && defined(slug.current)]{ "slug": slug.current }When a GROQ query feels slow, look at the {...} before you look at the [...]. And beware reusing a query written for another purpose — a [0...20] that was correct on a listing page becomes a silent 95% coverage gap when the same query is reused to enumerate every route.
Finding dead queries
Because queries are exported constants, dead ones are findable:
for q in $(grep -oP 'export const \K\w+Query' src/sanity/lib/queries.ts); do
echo "$(grep -rl "$q" src --include='*.ts*' | grep -vc queries.ts) $q"
done | sort -nAnything with 0 is a candidate → the shell techniques.
Related
Software engineering
Infrastructure & security
Computer science
Hardware & engineering