How to Use GROQ Projections to Reduce API Payload Size

GROQ (Graph-Relational Object Queries) is Sanity's query language, and projections are one of its most powerful features. A projection tells Sanity exactly which fields to include in the response — nothing more, nothing less. Without projections, every query returns the full document, including fields your frontend may never use.

What Is a GROQ Projection?

A projection is a set of field selectors wrapped in curly braces that follows a GROQ filter expression. It defines the shape of the response object. Think of it as the SELECT clause in SQL — you choose exactly what columns (fields) come back.

Without a projection, you get the entire document:

// No projection — returns every field on every matched document
*[_type == "post"]

With a projection, you get only what you ask for:

// Projection — returns only title, slug, and publishedAt
*[_type == "post"]{
  title,
  slug,
  publishedAt
}

Basic Projection Syntax

The simplest projection lists field names separated by commas inside curly braces. Each name maps directly to a field on the document.

*[_type == "product"]{
  _id,
  name,
  price,
  "imageUrl": image.asset->url
}

Notice the last line: "imageUrl": image.asset->url. This demonstrates two advanced features at once — field renaming and reference dereferencing — both covered in detail below.

Field Renaming in Projections

You can rename any field in the response by prefixing it with a quoted alias and a colon. This is useful when your frontend expects a different property name than what's stored in Sanity.

*[_type == "author"]{
  "id": _id,
  "fullName": name,
  "avatarUrl": photo.asset->url,
  "bio": biography[0].children[0].text
}

The response will use the alias keys (id, fullName, avatarUrl, bio) instead of the original Sanity field names. No schema changes required.

Dereferencing Related Documents

The -> operator dereferences a reference field, letting you reach into a related document and pull specific fields from it — all in a single query. This eliminates the need for multiple round-trips.

*[_type == "post"]{
  title,
  publishedAt,
  // Dereference the author reference and pick only name + slug
  "author": author->{
    name,
    "slug": slug.current
  },
  // Dereference each category in an array
  "categories": categories[]->{
    title,
    "slug": slug.current
  }
}

Without this, you'd receive raw reference objects like { _ref: "abc123", _type: "reference" } and need a second query to resolve them. Dereferencing inside a projection collapses that into one efficient call.

Computed Fields and Expressions

Projections can include computed values — not just raw field reads. You can use GROQ functions, string concatenation, array operations, and conditional logic directly inside a projection.

*[_type == "post"]{
  title,
  // Compute a full URL from slug
  "url": "/blog/" + slug.current,
  // Count the number of body blocks
  "readingTimeBlocks": count(body),
  // Extract only the first image from a Portable Text body
  "heroImage": body[_type == "image"][0].asset->url,
  // Boolean: is the post featured?
  "isFeatured": defined(featuredAt)
}

Conditional Projections with select()

The select() function lets you return different values based on conditions. This is especially useful when documents have variant shapes — for example, a content feed mixing posts, products, and events.

*[_type in ["post", "product", "event"]]{
  _type,
  title,
  "url": select(
    _type == "post"    => "/blog/" + slug.current,
    _type == "product" => "/shop/" + slug.current,
    _type == "event"   => "/events/" + slug.current
  ),
  // Include price only for products
  "price": select(_type == "product" => price, null)
}

Conditional Field Inclusion with defined()

Use defined() to guard against null values in your projection. This prevents undefined fields from polluting your response with null entries.

*[_type == "post"]{
  title,
  slug,
  // Only include excerpt if it exists on the document
  excerpt,
  // Safely dereference — returns null if no author is set
  "authorName": author->name,
  // Conditional: include thumbnail only if defined
  "thumbnail": defined(mainImage) => mainImage.asset->url
}

Nested Projections for Deep Objects

Projections can be nested to any depth. If a field contains an object or array of objects, you can project into it with another set of curly braces.

*[_type == "page"]{
  title,
  // Project into an array of section objects
  "sections": sections[]{
    _key,
    _type,
    heading,
    // Nested projection inside each section's items array
    "items": items[]{
      label,
      "icon": icon.asset->url
    }
  }
}

The Spread Operator: Selective Inclusion

The ... spread operator includes all fields of a document, which you can then combine with additional computed fields. Use it sparingly — it defeats the purpose of projections if used alone, but it's useful when you want most fields plus a few extras.

// Include everything, but also add a computed field
*[_type == "post"]{
  ...,
  "authorName": author->name,
  "categoryTitles": categories[]->title
}

A better pattern is to use spread selectively on a sub-object rather than the root document, keeping the top-level projection tight.

Measuring the Payload Difference

To understand the impact of projections, consider a typical Sanity blog post document. It might contain a full Portable Text body, multiple image references, SEO metadata, author references, category arrays, and internal system fields. A raw fetch of 20 such documents could easily return 1–2MB of JSON.

A listing page, however, only needs the title, slug, excerpt, published date, and a thumbnail URL. A projected query for those same 20 documents might return 15–30KB — a reduction of 98% or more.

// Listing page query — lean and fast
*[_type == "post"] | order(publishedAt desc) [0...20] {
  "id": _id,
  title,
  "slug": slug.current,
  excerpt,
  publishedAt,
  "thumbnail": mainImage.asset->url
}

This query returns exactly six fields per document. The full Portable Text body, all SEO fields, internal metadata, and unreferenced assets are never transmitted.