How to Model Nested Content Structures Without Losing Query Performance

Nested content structures are a natural part of any content model — pages have sections, sections have blocks, blocks have media. But every level of nesting you add has a cost: larger documents, more complex queries, and harder-to-maintain schemas. Getting the balance right is one of the most consequential decisions you will make when designing a CMS architecture.

When to Nest vs When to Reference

The fundamental question is: does this content exist independently, or does it only make sense as part of its parent? If the answer is the former, it should be a separate document with a reference. If the latter, it can be an inline object.

Use Inline Objects When:

• The data is tightly coupled to the parent and has no meaning outside it (e.g., a hero banner's CTA button).
• The content is never reused across documents.
• You always fetch the parent and child together — there is no use case for querying the child in isolation.
• The nesting depth stays at 2–3 levels maximum.

Use References When:

• The content is reused across multiple documents (e.g., an author profile, a product, a category).
• The content needs to be queried, filtered, or sorted independently.
• Updates to the content should propagate everywhere it is used without manual duplication.
• The content has its own publishing lifecycle (e.g., a product can be unpublished independently of the page that features it).

A practical rule of thumb: if you find yourself duplicating the same inline object across more than two documents, it is time to extract it into a standalone document type and use references.

The 3-Level Nesting Rule

A widely accepted heuristic in content modelling is to avoid nesting beyond 3 levels deep. Beyond that threshold, several problems compound:

• Document size grows significantly, increasing read payload even when you only need top-level fields.
• GROQ projections become verbose and error-prone to maintain.
• Schema changes at a deep level require cascading updates across all parent types.
• Editors lose context — it becomes unclear where a piece of content lives or how to find it.

GROQ Projection Examples for Nested Structures

GROQ projections are Sanity's primary tool for controlling query payload. Rather than fetching entire documents, you declare exactly which fields you need — including at arbitrary nesting depths.

Fetching Specific Fields from Inline Objects

If a page document has an inline hero object with a title, subtitle, and a large background image, you can project only the fields your frontend needs:

*[_type == "page"] {
  title,
  "hero": hero {
    title,
    subtitle,
    "backgroundImage": backgroundImage.asset->url
  }
}

This avoids fetching the full image asset document and any other fields on the hero object that the frontend does not use.

Dereferencing Across Multiple Levels

When you have references nested inside inline objects, use the dereference operator (->) to follow the reference and project only what you need from the referenced document:

*[_type == "article"] {
  title,
  "author": author-> {
    name,
    "avatar": avatar.asset->url
  },
  "categories": categories[]-> {
    title,
    slug
  }
}

Each -> operator performs a join. Chaining multiple -> operators in a single query is valid but adds latency — keep join depth to 2–3 levels in production queries.

Projecting Arrays of Blocks (Portable Text)

Portable Text arrays can contain inline references (e.g., embedded products or authors). Use a conditional projection to handle mixed block types efficiently:

*[_type == "post"] {
  title,
  "body": body[] {
    ...,
    _type == "reference" => @-> {
      _type,
      title,
      slug
    }
  }
}

The spread operator (...) includes all fields from standard blocks, while the conditional projection handles embedded references without over-fetching the referenced documents.

Performance Pitfalls to Avoid

1. Fetching Without Projections

The most common performance mistake is querying documents without a projection — returning the entire document tree. For documents with deep nesting or large Portable Text arrays, this can return megabytes of data for a single query. Always project.

// ❌ Avoid — returns entire document including all nested fields
*[_type == "page"]

// ✅ Prefer — returns only what the frontend needs
*[_type == "page"] {
  title,
  slug,
  "heroTitle": hero.title
}

2. Unbounded Reference Chains

Chaining too many dereference operators in a single query creates N+1-style join costs. Each -> is a separate lookup. If you find yourself writing three or more levels of ->, reconsider whether the data should be denormalised or the query split into multiple targeted fetches.

3. Circular References

A circular reference occurs when Document A references Document B, which references Document A. In GROQ, following a circular reference chain without a depth limit will cause an infinite loop or a query timeout. Sanity's query engine has safeguards, but the schema design should prevent circular references entirely. Common culprits include "related content" arrays where the same type references itself without a depth guard.

4. Over-Denormalisation

Denormalisation — copying data from a referenced document into the parent — speeds up reads by eliminating joins. However, it creates a consistency problem: when the source document changes, all copies must be updated. In Sanity, this typically requires a webhook-triggered update pipeline. Use denormalisation only for data that changes rarely and where read performance is critical (e.g., caching an author's name on an article for a listing page).

5. Large Array Documents

Sanity documents have a practical size limit. Storing hundreds of inline objects in a single document's array (e.g., all blog posts as inline objects on a "blog" document) creates a document that is slow to read, slow to write, and impossible to paginate. Arrays of inline objects should be bounded — if the array can grow unboundedly, each item should be its own document type.

Sanity-Specific Recommendations

Use Projections as Your API Contract

Treat each GROQ query as a typed API contract between your content model and your frontend. Define projection fragments as reusable constants in your codebase (e.g., AUTHOR_FRAGMENT, IMAGE_FRAGMENT) and compose them into page-level queries. This keeps queries maintainable and ensures projections stay in sync with schema changes.

Leverage Sanity's CDN for Cached Reads

Sanity's API CDN caches query results at the edge. Queries with tight projections produce smaller, more cacheable responses. A query that returns 2KB will be served from cache far more efficiently than one returning 200KB. Combine projection discipline with CDN usage for maximum read performance.

Use Weak References for Draft Relationships

When modelling relationships between documents that may not yet be published, use weak references (_weak: true). This prevents validation errors during content creation workflows while still allowing the relationship to be resolved once the referenced document is published.

Index Fields Used in Filters

GROQ filters on top-level fields (e.g., _type, slug.current, publishedAt) benefit from Sanity's built-in indexing. Filtering on deeply nested fields — especially inside arrays — bypasses these indexes and results in full document scans. Where possible, promote frequently filtered fields to the top level of the document.

Prefer Flat Document Types for Listing Queries

For listing pages (blog index, product catalogue), create a projection that returns only the fields needed for the card component — typically title, slug, a thumbnail image URL, and a short description. Never fetch the full document body for listing queries. This pattern is sometimes called a "summary projection" and dramatically reduces payload size for high-traffic listing endpoints.