Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท GraphQL Data Layer

GraphQL Basics in Gatsby

Understand the GraphQL data layer in Gatsby: nodes, fields, arguments, aliases, fragments and how a query returns exactly the shape of data your component asks for.

Gatsby has one rule that surprises newcomers: you do not read data files directly in your components. Instead, Gatsby loads all data into an internal store and lets you ask for what you need using GraphQL, a query language where you describe the shape of the data you want and get back exactly that shape, nothing more.

This is powerful for static sites. The build knows precisely which fields each page needs, so it ships only that data. This lesson teaches the GraphQL you need in Gatsby: queries, fields, arguments, aliases and fragments. You do not need to know GraphQL beforehand. Real queries are read-only; a stand-in mini engine lets you run query-like requests here.

Nodes and types

Everything in Gatsby's data layer is a node: an object with an id, a type and fields. A Markdown file becomes a MarkdownRemark node, an image becomes a File node, and the siteMetadata from your config lives on a single Site node. Gatsby builds a GraphQL schema from these nodes automatically (schema inference).

For every node type Gatsby creates two root query fields:

  • a singular field that returns one node: site, markdownRemark, file
  • a plural field that returns many: allMarkdownRemark, allFile, ... (the all prefix)

Your first query

GRAPHQL
query {
  site {
    siteMetadata {
      title
      description
    }
  }
}

The response mirrors the query:

JSON
{
  "data": {
    "site": {
      "siteMetadata": {
        "title": "Coffee Notes",
        "description": "Notes about brewing."
      }
    }
  }
}

If you leave description out of the query, it is absent from the response. That is the core idea: you ask, you receive exactly that.

Plural fields: nodes and edges

Plural fields return a list. The shortest form is nodes:

GRAPHQL
query {
  allMarkdownRemark {
    nodes {
      id
      frontmatter {
        title
        date(formatString: "MMMM D, YYYY")
      }
    }
  }
}

The older form uses edges { node { ... } }, which you will see in many tutorials. It returns the same data wrapped in extra objects. Prefer nodes.

Note date(formatString: ...): fields can take arguments. Gatsby adds handy ones such as formatString for dates and truncate or pruneLength for excerpts.

Filtering, sorting and limits

Plural fields accept filter, sort, limit and skip:

GRAPHQL
query {
  allMarkdownRemark(
    filter: { frontmatter: { draft: { ne: true } } }
    sort: { frontmatter: { date: DESC } }
    limit: 5
  ) {
    nodes {
      frontmatter { title }
    }
  }
}

Gatsby 5 uses the nested sort: { frontmatter: { date: DESC } } syntax; Gatsby 4 used sort: { fields: [frontmatter___date], order: DESC }. If you see the older form, you are reading a Gatsby 4 tutorial. GraphiQL and the data layer shows every operator.

Aliases and fragments

An alias renames a field in the response, so you can query the same field twice with different arguments:

GRAPHQL
query {
  latest: allMarkdownRemark(limit: 1, sort: { frontmatter: { date: DESC } }) {
    nodes { frontmatter { title } }
  }
  oldest: allMarkdownRemark(limit: 1, sort: { frontmatter: { date: ASC } }) {
    nodes { frontmatter { title } }
  }
}

A fragment is a reusable piece of a query:

GRAPHQL
fragment PostSummary on MarkdownRemark {
  id
  frontmatter { title date(formatString: "YYYY-MM-DD") }
}

query {
  allMarkdownRemark { nodes { ...PostSummary } }
}

In Gatsby, fragments declared in any file are available in all queries, which is how plugins ship ready-made fragments for images.

Stand-in: a mini GraphQL executor

Real Gatsby uses the GraphQL library. This stand-in is not GraphQL, but it parses a query's field selection and picks exactly those fields from a data tree, which is the heart of what a query does.

JS Stand-in: ask for fields, receive that shape

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that secret and description never appear, and neither do date or draft. Change the query to add description and rerun.

Stand-in: filter, sort and limit

JS Stand-in: plural fields with arguments

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Gatsby GraphQL queries are static: they run at build time and cannot take values from the browser. Variables come from page context (see page queries). For data that depends on the visitor, fetch it at runtime.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a GraphQL query return?

    The response mirrors the selection set of the query.
  2. 2. Which root field returns many nodes of the MarkdownRemark type?

    Gatsby creates singular and all-prefixed plural fields for each type.
  3. 3. What does an alias do?

    Aliases let you request the same field twice with different arguments under different names.
  4. 4. How is sorting written in Gatsby 5?

    Gatsby 5 uses nested field objects with ASC or DESC.

Summary

  • Gatsby puts all data into nodes and exposes it through GraphQL.
  • Each type has a singular field and an all... plural field returning nodes.
  • Queries return exactly the requested shape, which keeps page data small.
  • Plural fields accept filter, sort, limit and skip; fields can take arguments like formatString.
  • Aliases and fragments help avoid repetition; queries run at build time.

Next: Page Queries and useStaticQuery