Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท GraphQL Data Layer

GraphiQL and the Data Layer

Use the GraphiQL explorer at /___graphql to discover your Gatsby schema, then master filter operators, sort, limit, skip, distinct and group in plural queries.

When you build a Gatsby site you quickly ask: "What data do I actually have, and what is it called?" Gatsby answers this with GraphiQL, an in-browser tool that is available whenever the dev server runs. You can click through the whole schema, write and test queries, and copy a working query into your code. This lesson shows how to use it and then goes deep on filtering, sorting and grouping, the operators you will use constantly.

Everything shown for Gatsby is read-only; the stand-ins implement the operators on arrays so you can experiment.

Opening GraphiQL

Start the dev server (gatsby develop, see the Gatsby CLI) and visit:

TEXT
http://localhost:8000/___graphql

Three panels matter:

  1. Explorer (left): a tree of every type and field. Tick boxes to build a query without typing.
  2. Editor (middle): the query text. Press Ctrl+Space for autocomplete, Ctrl+Enter to run.
  3. Result (right): the JSON response.

A Docs button opens the generated schema documentation: every root field, every argument, every type. If a field you expect is missing, the node probably does not exist yet. Query allFile to check whether your source plugin found your files.

GraphiQL is part of the development server only. It does not exist in the production build, so nothing is exposed to your visitors.

Filter operators

filter takes an object that mirrors the node's shape. Each leaf has an operator:

Operator Meaning Example
eq equals { title: { eq: "Espresso" } }
ne not equal { draft: { ne: true } }
in value is in a list { category: { in: ["tea", "coffee"] } }
nin value not in a list { category: { nin: ["draft"] } }
regex matches a regular expression { title: { regex: "/^Esp/i" } }
glob matches a wildcard { relativePath: { glob: "posts/*.md" } }
lt, lte, gt, gte comparisons { price: { gte: 10 } }
elemMatch some list item matches { tags: { elemMatch: { eq: "gatsby" } } }

Several keys inside one filter object are combined with AND. Gatsby does not have an or operator in filters; run two queries or filter in JavaScript when you need OR.

GRAPHQL
query {
  allMarkdownRemark(
    filter: {
      frontmatter: { draft: { ne: true }, category: { in: ["coffee", "tea"] } }
    }
  ) {
    totalCount
    nodes { frontmatter { title } }
  }
}

totalCount is useful for pagination: it returns the number of matches before limit and skip apply.

Sorting, limits and paging

GRAPHQL
query ($limit: Int!, $skip: Int!) {
  allMarkdownRemark(
    sort: [{ frontmatter: { date: DESC } }, { frontmatter: { title: ASC } }]
    limit: $limit
    skip: $skip
  ) {
    nodes { frontmatter { title date } }
    pageInfo { currentPage pageCount hasNextPage }
  }
}

Pass an array to sort to sort by several fields. limit and skip with variables give you paginated lists, an application of programmatic page creation.

distinct and group

Two helper fields summarize a list:

GRAPHQL
query {
  allMarkdownRemark {
    tags: distinct(field: { frontmatter: { tags: SELECT } })
    byCategory: group(field: { frontmatter: { category: SELECT } }) {
      fieldValue
      totalCount
      nodes { frontmatter { title } }
    }
  }
}

distinct returns the unique values of a field (all tags in use). group returns one entry per value with its nodes and counts, ideal for tag pages and category menus.

flowchart LR
  A["All nodes"] --> B["filter"]
  B --> C["sort"]
  C --> D["skip"]
  D --> E["limit"]
  E --> F["nodes returned"]
  B --> G["totalCount"]

Order of operations: filter and sort first, then skip and limit. totalCount reflects the filtered list.

Stand-in: the query operators on an array

This stand-in is not Gatsby, but it implements filter operators, multi-field sort, skip, limit, totalCount, distinct and group.

JS Stand-in: filter, sort, group

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

No output.

Change limit to 3 and note that totalCount stays the same: it counts matches, not the returned slice.

Stand-in: building a tag index

Tag pages need the unique tags and their counts, exactly what group provides.

JS Stand-in: distinct tags with counts

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

No output.

Debugging missing data

  • Query the plural root (allFile, allMarkdownRemark) with totalCount to see whether any nodes exist.
  • A field that exists on only some nodes may be absent from the schema entirely. This is a schema inference problem; define the type explicitly.
  • Wrong plugin path options are the most frequent cause of empty results.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where is GraphiQL available?

    GraphiQL is a development-server tool and is not in the production build.
  2. 2. How are several keys in one filter object combined?

    All conditions must be true. There is no or operator in Gatsby filters.
  3. 3. What does totalCount return?

    It counts all nodes matching the filter, which is what pagination needs.
  4. 4. Which helper returns one entry per category with its nodes?

    group returns fieldValue, totalCount and nodes for each value.

Summary

  • GraphiQL at /___graphql shows the schema, runs queries and writes them for you.
  • Filters use operators (eq, ne, in, regex, glob, gte, elemMatch, ...) and combine with AND.
  • sort accepts several fields; limit and skip page results; totalCount counts all matches.
  • distinct and group summarize values for tag and category pages.
  • Missing data usually means a missing node, a wrong plugin path or an inferred-schema gap.

Next: Creating Pages Programmatically