Skip to main content

GraphQL Reference

Work in progress - pull requests showing additional examples are strongly encouraged.

Intro

This page will walk you through a series of GraphQL queries, each designed to demonstrate a particular feature of GraphQL. You’ll be querying the real schema used on gatsbyjs.org so feel free to experiment and poke around the innards of our site!

You’ll be using GraphiQL, an interactive editor you can also use while building your Gatsby site.

Basic query

Let’s start with the basics, pulling up the site title from your gatsby-config.js’s siteMetaData. Here the query is on the left and the results are on the right.

Try editing the query to include the description from siteMetadata. When typing in the query editor you can use Ctrl + Space to see autocomplete options and Ctrl + Enter to run the current query.

A longer query

Gatsby structures its content as collections of nodes, which are connected to each other with edges. In this query you ask for the total count of plugins in this Gatsby site, along with specific information about each one.

Try using the editor’s autocomplete (Ctrl + Space) to get extended details from the packageJson nodes.

Limit

There are several ways to reduce the number of results from a query. Here totalCount tells you there’s a few hundred results, but limit is used to show only the first two.

Skip

Skip over a number of results. In this query skip is used to omit the first 3 results.

Filter

In this query filter and the ne (not equals) operator is used to show only results that have a title.

Gatsby relies on Sift to enable MongoDB-like query syntax for object filtering. This allows Gatsby to support operators like eq, ne, in, regex and querying nested fields through the __ connector.

It is also possible to filter on multiple fields - just separate the individual filters by a comma (works as an AND):

filter: { contentType: { in: ["post", "page"] }, draft: { eq: false } }

A good video tutorial on this is here.

TODO: Add more advanced examples

Sort

The ordering of your results can be specified with sort. Here the results are sorted in ascending order of frontmatter’s date field.

TODO: Can you sort on multiple fields?

Format

Dates can be formatted using the formatString function.

Gatsby relies on Moment.js to format the dates. This allows you to use any tokens in your string. See moment.js documentation for more tokens.

Example: anotherDate(formatString: "dddd, MMMM Do YYYY, h:mm:ss a") # Sunday, August 5th 2018, 10:56:14 am

TODO: Expand on the possibilities of formatting - which fields can be formatted? What are the available formatting options?

Sort, filter, limit & format together

This query combines sorting, filtering, limiting and formatting together.

Query variables

In addition to adding query arguments directly to queries, GraphQL allows to pass in “query variables”. These can be both simple scalar values as well as objects.

The query below is the same one as the previous example, but with the input arguments passed in as “query variables”.

To add variables to page component queries, pass these in the context object when creating pages.

Group

You can also group values on the basis of a field e.g. the title, date or category and get the field value, the total number of occurrences and edges.

The query below gets us all authors (fieldValue) who wrote a blogpost and how many blogposts (totalCount) they wrote. In addition we’re grabbing the title and slug of the author’s articles.

Fragments

Fragments are a way to save frequently used queries for re-use. To create a fragment, define it in a query and export it as a named export from any file Gatsby is aware of. A fragment is available for use in any other GraphQL query, regardless of location in the project. Fragments defined in a Gatsby project are global, so names must be unique.

The query below defines a fragment to get the site title, and then uses the fragment to access this information.

Aliasing

Want to run two queries on the same datasource? You can do this by aliasing your queries. See below for an example:

When you use your data, you will be able to reference it using the alias instead of the root query name. In this example, that would be data.someEntries or data.someMoreEntries instead of data.allMarkdownRemark.

Where next?

Try running your own queries, check out the rest of the docs or run through the tutorial.


Was this helpful? edit this page on GitHub