Gatsby GraphQL Data Layer — Querying Data in Gatsby

In this tutorial, you will learn about Gatsby Graphql Data Layer. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn the Gatsby GraphQL data layer: how data is collected from sources, the GraphQL schema, and interactive querying with GraphiQL for React static sites.

In this lesson, you'll understand how Gatsby's GraphQL layer works, how to explore data with GraphiQL, and how to structure queries.

What You'll Learn

How Gatsby builds a GraphQL schema from plugins, how to use GraphiQL to explore data, and how to construct queries for different data types.

Why It Matters

Gatsby's data layer unifies data from multiple sources (files, CMS, APIs) into a single GraphQL API. This makes data access consistent and queryable.

flowchart TD
    A[Source Plugins] --> B[Raw Nodes]
    B --> C[Transformer Plugins]
    C --> D[GraphQL Schema]
    D --> E[GraphiQL Explorer]
    D --> F[Page Queries]
    D --> G[Static Queries]
    style D fill:#639,color:#fff

Exploring Data in GraphiQL

Start the dev server and visit http://localhost:8000/___graphql:

# Explore available data types in the Docs panel
query SiteMetadata {
  site {
    siteMetadata {
      title
      description
      author
    }
  }
}

Output: The query returns your site's metadata from gatsby-config.js. GraphiQL provides autocomplete, documentation, and a query history.

Querying Files

Query files from gatsby-source-filesystem:

query AllFiles {
  allFile {
    totalCount
    edges {
      node {
        relativePath
        extension
        size
        publicURL
      }
    }
  }
}

Output: Returns metadata about all files in sourced directories: file count, paths, sizes, and public URLs.

Querying Markdown

With gatsby-transformer-remark, query transformed Markdown:

query AllMarkdown {
  allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
    totalCount
    nodes {
      frontmatter {
        title
        date(formatString: "MMMM D, YYYY")
        tags
      }
      excerpt(pruneLength: 200)
      timeToRead
      fields {
        slug
      }
    }
  }
}

Output: Returns all Markdown posts sorted by date, with frontmatter, excerpt, reading time, and slug.

Query Parameters and Filtering

Filter and sort query results:

query FilteredPosts {
  allMarkdownRemark(
    filter: {
      frontmatter: {
        date: { gte: "2026-01-01" }
        tags: { in: ["gatsby", "react"] }
        draft: { eq: false }
      }
    }
    sort: { frontmatter: { date: DESC } }
    limit: 10
  ) {
    nodes {
      frontmatter { title date }
    }
  }
}

Output: Returns up to 10 published posts from 2026 with Gatsby or React tags, sorted newest first.

GraphQL Aliases and Fragments

query HomePage {
  recentPosts: allMarkdownRemark(
    sort: { frontmatter: { date: DESC } }
    limit: 5
  ) {
    nodes {
      frontmatter { title date }
      excerpt
    }
  }

  featuredPosts: allMarkdownRemark(
    filter: { frontmatter: { featured: { eq: true } } }
  ) {
    nodes {
      frontmatter { title }
    }
  }
}

Output: The query uses aliases (recentPosts, featuredPosts) to fetch two different lists in one request. Fragments can reuse common field selections.

Common Mistakes

1. Trying to query non-existent fields: Check available fields in GraphiQL's Docs panel. A typo returns an error.
2. Using strings for date fields without formatString: Use formatString: "MMMM D, YYYY" to format dates. Without it, dates are raw ISO strings.
3. Not filtering drafts in queries: If you use a draft frontmatter field, filter draft: { eq: false } to exclude unpublished content.
4. Querying without checking GraphiQL first: Always Prototype queries in GraphiQL before adding them to components.
5. Forgetting fragments for reusable queries: Define fragments for commonly queried fields (image data, SEO fields) to avoid repetition.

Practice Questions

1. What is the URL for the GraphiQL explorer? Answer: http://localhost:8000/___graphql. It opens an interactive IDE for building and testing queries.

2. How do you filter query results in Gatsby? Answer: Use the filter argument with operators like eq, in, gte, lte, regex. Example: filter: { frontmatter: { tags: { in: ["react"] } } }.

3. What is a GraphQL alias? Answer: An alias lets you rename a query field in the result. Used to fetch multiple queries of the same type: recentPosts: allMarkdownRemark(...).

4. What does allMarkdownRemark return? Answer: All Markdown files transformed by gatsby-transformer-remark, with frontmatter, HTML, excerpt, and metadata fields.

Challenge

Connect a third-party API using gatsby-source-graphql and query its data alongside local filesystem data in a single page query. Build a dashboard that combines both data sources.

Mini Project

Create a data dashboard page that queries: site metadata, recent blog posts, image metadata, and static file listings. Display the results in a card-based layout.

FAQ

What's Next

Learn about Gatsby useStaticQuery Hook to query data in any component without page context.