GraphQL distinct queries for efficient data filtering

GraphQL distinct refers to the common developer task of fetching unique or de-duplicated values from a data source using a GraphQL API. Unlike SQL, GraphQL has no built-in DISTINCT keyword, so developers must implement this logic on the server side — inside a resolver, at the database layer, or through framework-level helpers like Hasura’s distinct_on or Gatsby’s distinct() aggregation. Getting this wrong leads to data over-fetching, bloated payloads, and unnecessary strain on both server and client.

Purpose of this guide

This guide is for developers who need to retrieve unique values through a GraphQL API and aren’t sure where to implement the logic. You’ll get working code examples for three major environments — Gatsby 5, Apollo Server, and Hasura — plus a clear explanation of the Gatsby 5 SELECT keyword, performance optimization strategies, filtering patterns, and a comparison with group functions. By the end, you’ll know exactly how to implement distinct queries cleanly and scalably, regardless of your stack.

Introduction

GraphQL distinct queries are a go-to solution when you need unique values from a dataset — think populating a category dropdown, building a tag cloud, or powering a faceted search interface. The challenge is that GraphQL’s specification has no standardized DISTINCT operator, so the implementation falls to you: the resolver, the database query, or a framework helper. Done right, this means less data over the wire, simpler frontend code, and a faster user experience. Done wrong, you end up retrieving thousands of records just to deduplicate them on the client.

This guide covers the full picture — from what distinct queries actually are, through Gatsby 5’s syntax changes, Apollo resolver patterns, and Hasura’s native distinct_on, to performance optimization and common pitfalls. Whether you’re building a CMS, an e-commerce catalog, or an analytics dashboard, you’ll find actionable patterns here.

What are GraphQL distinct queries

A GraphQL distinct query is an operation that returns only unique values for a specified field, eliminating duplicates from the result set at the API layer. Instead of fetching every post and extracting categories on the frontend, you ask the API for a deduplicated list of categories directly. The result is a smaller payload, no client-side processing, and a single source of truth for unique values across your application.

Think of it like asking a librarian for a list of unique genres in the library rather than pulling every book and reading its genre label. You get a clean, ready-to-use list — not raw data to sift through.

GraphQL itself has no standardized distinct operator, but major frameworks each provide their own solution. Hasura offers distinct_on for PostgreSQL-backed APIs. Gatsby 5 exposes a distinct() aggregation resolver using the SELECT enum syntax. Apollo Server requires a custom resolver, but gives you full control over the deduplication logic. For a broader look at how queries work, see the official GraphQL query documentation.

When to use distinct queries in GraphQL

Distinct queries are the right tool when your UI needs a list of options — not a list of records. The moment you catch yourself fetching full entities just to extract one field and deduplicate it on the client, that’s the sign to move the logic to the API.

Content management systems are a natural fit. A blog with hundreds of posts might have only ten unique categories — a distinct query returns those ten values directly, without making the frontend process hundreds of post objects. E-commerce catalogs benefit similarly: instead of scanning all products to find unique brands, colors, or sizes, a distinct query returns the filter options ready to render.

Mobile applications get a disproportionate benefit. Bandwidth and processing constraints make client-side deduplication expensive on mobile. Moving distinct logic to the API directly reduces payload size and speeds up rendering, which matters for both user experience and data costs.

The business case is clear: distinct queries reduce development overhead, eliminate duplicate deduplication logic across teams, and scale gracefully as datasets grow. A pattern that works on 1,000 records with client-side filtering often breaks at 100,000 — distinct queries at the API layer stay efficient at any size.

Example use case: obtaining distinct values from collections

Consider a content website that needs to extract unique categories from blog posts to populate a category filter dropdown. Multiple posts share the same categories, so a standard query returns duplicates that need client-side processing. A distinct query solves this at the source.

Sample data structure:

[
  {
    "title": "GraphQL Best Practices",
    "frontmatter": {
      "category": "Development",
      "tags": ["graphql", "api"]
    }
  },
  {
    "title": "React Performance Tips",
    "frontmatter": {
      "category": "Development",
      "tags": ["react", "performance"]
    }
  },
  {
    "title": "CSS Grid Layout",
    "frontmatter": {
      "category": "Design",
      "tags": ["css", "layout"]
    }
  }
]

A standard query would return all three posts with their categories, requiring the frontend to deduplicate. The distinct query returns only the unique values:

query GetUniqueCategories {
  allMarkdownRemark {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

Response:

{
  "data": {
    "allMarkdownRemark": {
      "distinct": ["Development", "Design"]
    }
  }
}

The API becomes the single source of truth for category values. Any component that needs the category list makes one query and gets clean data — no deduplication logic, no risk of inconsistency between components. As the content collection grows to thousands of posts, the query continues to return the same compact array of unique values rather than processing the full dataset on the client.

Sorting distinct results effectively

Distinct results from Gatsby’s distinct() resolver are returned as a plain array of strings. To sort them, apply JavaScript’s .sort() after the query returns — the distinct() argument doesn’t accept sorting directly.

query GetUniqueCategories {
  allMarkdownRemark {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

// Sort the result after the query
const sortedCategories = data.allMarkdownRemark.distinct.sort();

In Hasura, sorting is built into the query via order_by, which pairs naturally with distinct_on:

query GetSortedUniqueCategories {
  posts(distinct_on: category, order_by: {category: asc}) {
    category
  }
}

Note that in Hasura, order_by must include the same fields used in distinct_on as its first ordering criteria — otherwise the query will return an error. This is a PostgreSQL constraint, not a Hasura limitation.

Implementation across different GraphQL environments

GraphQL’s specification defines query structure but says nothing about distinct operations, leaving each framework to implement it differently. Gatsby provides a built-in distinct() resolver. Hasura delegates to PostgreSQL’s native DISTINCT ON. Apollo requires a custom resolver. Understanding each approach matters both for implementing correctly now and for evaluating frameworks when starting new projects.

Distinct in Gatsby GraphQL

Gatsby’s built-in distinct functionality is part of its GraphQL data layer and is available on all connection types (e.g., allMarkdownRemark, allMdx). It runs at build time for static sites, meaning the deduplication overhead doesn’t affect runtime performance.

Gatsby 5 introduced a breaking change in the syntax for field selection. The old triple-underscore path format (frontmatter___category) was replaced with a nested object selector using the SELECT enum keyword.

Gatsby 4 syntax:

query Gatsby4DistinctExample {
  allMarkdownRemark {
    distinct(field: frontmatter___category)
  }
}

Gatsby 5 syntax:

query Gatsby5DistinctExample {
  allMarkdownRemark {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

The challenge of finding correct syntax in Gatsby 5

Developers upgrading from Gatsby 4 frequently hit this error when using the old syntax:

GraphQL Error: Field "distinct" argument "field" of type "FieldSelectorEnum"
is required but not provided.

The error message doesn’t tell you what the correct format is. The old syntax:

# Does NOT work in Gatsby 5
query IncorrectSyntax {
  allMarkdownRemark {
    distinct(field: frontmatter___category)
  }
}

The correct Gatsby 5 syntax:

# Works in Gatsby 5
query CorrectSyntax {
  allMarkdownRemark {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

When you run this in GraphiQL on a Gatsby 5 site, autocompletion will show SELECT as the only available value inside the field object — that’s the confirmation you’re using the right structure.

Understanding the SELECT keyword in Gatsby 5

The SELECT keyword is a value of the FieldSelectorEnum type in Gatsby’s generated schema. It replaces the flat string path approach with a typed, nested object that the GraphQL engine can validate at parse time — before the query executes. This means field reference errors surface immediately in your IDE or during the build, rather than silently returning empty arrays at runtime.

In practice, you can use SELECT on any scalar field nested inside frontmatter or other node types:

query MultipleDistinctFields {
  allMarkdownRemark {
    categories: distinct(field: {frontmatter: {category: SELECT}})
    authors: distinct(field: {frontmatter: {author: SELECT}})
  }
}

The schema validation also means better autocompletion in GraphiQL and IDE plugins — you’ll see valid field paths suggested as you type.

Distinct in Apollo GraphQL

Apollo Server has no built-in distinct operation. You implement it in a custom resolver, which gives you full control over the deduplication logic and lets you integrate with any data source or apply business rules during extraction.

// Apollo Server resolver
const resolvers = {
  Query: {
    distinctCategories: async (parent, args, context) => {
      const allPosts = await context.dataSources.posts.getAllPosts();
      const categories = allPosts.map(post => post.category).filter(Boolean);
      return [...new Set(categories)].sort();
    }
  }
};

Schema definition:

type Query {
  distinctCategories: [String!]!
}

Client query:

query GetDistinctCategories {
  distinctCategories
}

For better performance with large datasets, push the deduplication to the database rather than loading all records into the resolver:

// More efficient: let the database handle distinct
const resolvers = {
  Query: {
    distinctCategories: async (parent, args, context) => {
      // SQL: SELECT DISTINCT category FROM posts WHERE published = true
      return context.db.query(
        'SELECT DISTINCT category FROM posts WHERE published = $1 ORDER BY category',
        [true]
      ).then(rows => rows.map(r => r.category));
    }
  }
};

When you need distinct values across multiple fields simultaneously, consider using DataLoader to batch and cache these queries and avoid N+1 issues if distinct resolvers are called from multiple places in the same request.

Distinct in Hasura

Hasura provides native distinct functionality through its auto-generated GraphQL API, delegating directly to PostgreSQL’s DISTINCT ON clause. No custom resolver needed — the capability is available out of the box for every table and view in your database.

“You can fetch rows with only distinct values of a column using the distinct_on argument. It is typically recommended to use order_by along with distinct_on to ensure we get predictable results.”
— Hasura GraphQL Docs, 2024
Source link

query HasuraDistinctExample {
  posts(distinct_on: category, order_by: {category: asc}) {
    category
  }
}

distinct_on accepts an array of columns, enabling distinct operations across multiple fields. When using multiple columns, order_by must list those same columns first — this is a PostgreSQL requirement for DISTINCT ON to produce deterministic results.

query MultiColumnDistinct {
  posts(
    distinct_on: [category, author_id],
    order_by: [
      {category: asc},
      {author_id: asc},
      {created_at: desc}
    ]
  ) {
    category
    author_id
    title
    created_at
  }
}

Because Hasura uses PostgreSQL under the hood, all standard PostgreSQL indexing strategies apply. An index on the distinct_on column — especially a partial index when combined with a filter — can dramatically reduce query execution time.

Filtering distinct results

Combining filtering with distinct queries creates focused, efficient data retrieval. The key decision is whether to filter before or after the distinct operation.

Pre-filtering applies conditions before extracting distinct values, reducing the working dataset. This is almost always the better approach for performance when filters eliminate a meaningful portion of records:

query FilteredDistinctCategories {
  allMarkdownRemark(
    filter: {
      frontmatter: {
        published: {eq: true},
        date: {gte: "2024-01-01"}
      }
    }
  ) {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

In Hasura, the equivalent uses the where argument alongside distinct_on:

query HasuraFilteredDistinct {
  posts(
    where: {published: {_eq: true}},
    distinct_on: category,
    order_by: {category: asc}
  ) {
    category
  }
}

Post-filtering (filtering the distinct results after extraction) is less common and typically handled in application logic rather than at the GraphQL layer — for example, stripping internal or deprecated category values from a list before passing it to the UI.

For complex filter combinations, pre-filtering always wins on performance because it reduces the rows the distinct operation must process. Use post-filtering only when the filter criteria apply to the distinct values themselves, not the underlying dataset.

Optimizing performance with distinct queries

Performance optimization for distinct queries works at three levels: the database, the query structure, and the application cache. The biggest gains almost always come from the database.

A composite index that covers both the distinct field and any filter conditions lets the database satisfy the query from the index alone, without a table scan:

-- Covers: distinct_on category WHERE published = true
CREATE INDEX idx_posts_published_category
ON posts (category, published)
WHERE published = true;

Distinct results are ideal candidates for caching because category lists, tag sets, and filter options change far less frequently than the underlying content. A short TTL cache (5–60 minutes depending on your update frequency) can absorb the majority of distinct query load:

const getDistinctCategories = async () => {
  const cacheKey = 'distinct_categories';
  let categories = await cache.get(cacheKey);

  if (!categories) {
    categories = await db.query(
      'SELECT DISTINCT category FROM posts WHERE published = true ORDER BY category'
    ).then(rows => rows.map(r => r.category));
    await cache.set(cacheKey, categories, 3600); // 1 hour TTL
  }

  return categories;
};

In production, track distinct query execution time as a dedicated metric. Category and filter queries are called on nearly every page load — a 200ms distinct query hitting a table without an index will show up in your p95 latency before anything else.

Using group functions as an alternative approach

When you need unique values and a count per value, group functions are more efficient than running a distinct query followed by a separate count query.

In Gatsby, the group() resolver returns unique values with a totalCount for each bucket — useful for category menus that show post counts:

query GroupedCategories {
  allMarkdownRemark {
    group(field: {frontmatter: {category: SELECT}}) {
      fieldValue
      totalCount
    }
  }
}

Response:

{
  "data": {
    "allMarkdownRemark": {
      "group": [
        {"fieldValue": "Development", "totalCount": 15},
        {"fieldValue": "Design", "totalCount": 8}
      ]
    }
  }
}

If your UI displays “Development (15)” style labels, group functions eliminate a second API call. If you only need the category names, distinct is simpler and faster.

Common pitfalls and solutions

Wrong field type: Distinct only works on scalar fields. Pointing it at an object or array field causes an error or silent empty results:

# Wrong: frontmatter is an object, not a scalar
query ProblematicDistinct {
  allMarkdownRemark {
    distinct(field: {frontmatter: SELECT})
  }
}

# Correct: target the scalar field inside the object
query CorrectDistinct {
  allMarkdownRemark {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

Null values: If a field is optional, null may appear in distinct results. Filter it out before rendering:

const categories = data.allMarkdownRemark.distinct.filter(Boolean);

Hasura missing order_by: Using distinct_on without order_by on the same field returns non-deterministic results and may cause a database error:

# Will error or return inconsistent results
query BadHasuraDistinct {
  posts(distinct_on: category) {
    category
  }
}

# Correct: order_by must lead with the distinct_on field
query GoodHasuraDistinct {
  posts(distinct_on: category, order_by: {category: asc}) {
    category
  }
}

Practical examples and use cases

Here are three implementation patterns that cover the most common real-world uses of distinct queries.

Dynamic category navigation (Gatsby CMS): Category menus that automatically reflect published content without manual maintenance:

query DynamicCategoryNavigation {
  allMarkdownRemark(filter: {frontmatter: {published: {eq: true}}}) {
    distinct(field: {frontmatter: {category: SELECT}})
  }
}

E-commerce filter options (Hasura + PostgreSQL): Extract unique values for product filters directly from the catalog:

query ProductBrandFilter {
  products(
    where: {active: {_eq: true}},
    distinct_on: brand,
    order_by: {brand: asc}
  ) {
    brand
  }
}

Run a separate query per filter dimension (brand, size, color) rather than trying to get all distinct values in one query — this keeps each query simple and independently cacheable.

Analytics dimensions (Apollo + custom resolver): Supply unique segment and region values to a reporting dashboard:

const resolvers = {
  Query: {
    analyticsDimensions: async (_, __, { db }) => {
      const [segments, regions] = await Promise.all([
        db.query('SELECT DISTINCT segment FROM customers ORDER BY segment'),
        db.query('SELECT DISTINCT region FROM customers ORDER BY region')
      ]);
      return {
        segments: segments.rows.map(r => r.segment),
        regions: regions.rows.map(r => r.region)
      };
    }
  }
};