Mastering Hygraph API performance: Optimizing queries and schema design

This 3-part guide helps you maximize the potential of the Hygraph API. In the previous part of this guide, we walked through how Hygraph serves your content and how to work with rate limits. Today, we will look at how to optimize query performance and schema design.

#Optimizing query performance

Well-designed queries are the foundation of a responsive application. Here are some useful tools to help you optimize your queries.

Query optimization strategies

1. Use appropriate fetch sizes

Match your first parameter to actual needs:

# ❌ Over-fetching for a single result
query {
  pages(where: { slug: "about" }, first: 1000) {
    title
  }
}

# ✅ Right-sized for the use case
query {
  pages(where: { slug: "about" }, first: 1) {
    title
  }
}

2. Fetch only required fields

Select only the fields your UI actually uses:

# ❌ Fetching everything
query {
  post(where: { id: "..." }) {
    id
    title
    body
    author
    comments
    metadata
    seoData
    relatedPosts
  }
}

# ✅ Fetching what's needed for the card component
query {
  post(where: { id: "..." }) {
    id
    title
  }
}

3. Implement pagination

For collections, use cursor-based pagination to fetch data in manageable chunks:

query GetPaginatedPosts($first: Int, $after: String) {
  postsConnection(first: $first, after: $after) {
    edges {
      node {
        id
        title
        slug
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

4. Optimize union queries

Modular content blocks using unions can become expensive. A two-step approach reduces complexity:

Step 1: Fetch block types and IDs

query {
  page(where: { id: "..." }) {
    title
    blocks {
      __typename
      ... on Node {
        id
      }
    }
  }
}

Step 2: Batch-fetch blocks by type

query BlockContent {
  heroes: heros(where: { id_in: ["id1"] }) {
    title
    ctaLink
  }
  grids: grids(where: { id_in: ["id2", "id3"] }) {
    title
    subtitle { markdown }
  }
}

This pattern converts one expensive union query into multiple simpler, more cacheable queries.

#Schema design for performance

Many optimization opportunities exist at the schema level. Thoughtful content modeling pays dividends in query performance and cache efficiency.

Performance-oriented principles

1. Separate editorial and delivery concerns

Design models that serve clear purposes rather than trying to handle every use case:

2. Prefer flat structures on high-traffic paths

Homepage and navigation queries are executed frequently. Keep these data structures shallow and purpose-built.

3. Limit reference depth

Each level of nested references multiplies query complexity. For frequently-accessed content, consider denormalizing data that would otherwise require deep traversal.

4. Standardize asset usage with wrapper components

Rather than referencing assets directly across many models, use a consistent component pattern:

ImageBlock (Component)
├── asset (Asset reference)
├── altText
├── caption
└── attribution

This simplifies asset queries and enables consistent optimization across your schema.

#Quick reference: Diagnostic checklist

Slow Queries?

#What’s next

Optimizing queries and schema design is only part of the performance story. We hope that this guide has been helpful for you. In the final part of this guide, we’ll focus on managing asset traffic. If you have any questions about mastering the Hygraph API, you can reach out to us at support@hygraph.com.