Work in progress - pull requests showing additional examples are strongly encouraged.
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.
Let’s start with the basics, pulling up the site
title from your
siteMetaData. Here the query is on the left and the results are on the right.
Try editing the query to include the
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
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.
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
regex and querying nested fields through the
A good video tutorial on this is here.
TODO: Add more advanced examples
The ordering of your results can be specified with
sort. Here the results are sorted in ascending order of
TODO: Can you sort on multiple fields?
Dates can be formatted using the
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.
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.
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 occurences 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
slug of the author’s articles.