Skip to main content

Overview

GroqD

GroqD is a GROQ query builder, designed to give the best GROQ developer experience possible.

It gives you the flexibility of GROQ, the runtime safety of Zod, and provides schema-aware auto-completion and type-checking.

What is GROQ?

GROQ is Sanity's open-source query language.

"It's a powerful and intuitive language that's easy to learn. With GROQ you can describe exactly what information your application needs, join information from several sets of documents, and stitch together a very specific response with only the exact fields you need."

Usage Example​

GroqD uses a strongly-typed chaining syntax to build queries:

import { createGroqBuilder } from 'groqd';
// 👇 Import Sanity types, generated by your Sanity project. See "Configuration" docs for more details.
import type * as SanityTypes from "./sanity.types.ts";

// 👇 Create a strongly-typed query builder:
const q = createGroqBuilder<{
  schemaTypes: SanityTypes.AllSanitySchemaTypes
  referenceSymbol: typeof SanityTypes.internalGroqTypeReferenceTo;
}>();

// ✨ Write strongly-typed queries, with auto-complete and runtime safety!
const productsQuery = (
  q.star
   .filterByType("products")
   .order("price desc")
   .slice(0, 10)
   .project(sub => ({
     name: q.string(),
     price: q.number(),
     slug: sub.field("slug.current", q.string()),
     imageUrls: sub.field("images[]").deref().field("url", q.string())
   }))
);

Everything in the above query is strongly-typed, according to the Sanity schema defined in your sanity.config.ts. This means you get auto-complete for all strings, including "price desc" and "slug.current"!

The example above generates a GROQ query like this:

*[_type == "products"] | order(price desc) [0...10] {
  name,
  price,
  "slug": slug.current,
  "imageUrls": images[]->url
}

and executing the query will return strongly-typed results:

const results = await runQuery(productsQuery);
/*
 * results: Array<{ 
 *   name: string,
 *   price: number,
 *   slug: string,
 *   imageUrls: Array<string>,
 * }>
 */

Why GroqD over raw GROQ?​

Sanity's CLI can generate types from your raw GROQ queries. This works well for simple use-cases.
However, GroqD aims to maximize the developer experience, improve generated types, and ensure scalability. Namely, it adds:

  • Auto-completion - write queries quickly and confidently
  • Runtime validation - ensure data integrity, catch errors early
  • Transformation - map values at runtime, like parsing dates
  • Fragments - create reusable query fragments, and compose queries from other fragments

The Playground​

We also provide a Vision-like Sanity Studio tool for experimenting with groqd queries and running them against your actual dataset.

Screenshot of groqd playground in action

The playground is a drop-in Sanity plugin, and is an easy way to test out groqd within your dataset. See the playground docs for more information on the playground.