Skip to main content

Overview

The root q object​

The q object (created in the Configuration section) has 3 main purposes:

Start a query chain​

All query chains start with either q.star or q.project(...). All methods of a query chain return a new chainable instance of GroqBuilder. Every chain is immutable, and can be reused if needed.

See the Filters and Projections documentation for more details.

Provide Zod's validation functions​

The root q object has shortcuts for Zod's validation functions, like q.string() and q.number(). These are identical to zod.string() and zod.number(), and are added to the q object for convenience.

See the Validation documentation for more details.

Create reusable fragments​

You can also define reusable "projection fragments" using the q.fragment<T>() method.

See the Fragments documentation for more details.

An example query​

const top10ProductsQuery = (
   q.star
    .filterByType("product")
    .order("price asc")
    .slice(0, 10)
    .project(sub => ({
      title: q.string(),
      price: q.number(),
      images: sub.field("images[]").deref().project({
        width: q.number(),
        height: q.number(),
        url: q.string(),
      })
    }))
);