Querying Data in Pages with GraphQL
graphql tag enables page components to retrieve data via a GraphQL query.
If you’re curious, you can also read more about why Gatsby uses GraphQL.
Gatsby uses the concept of a page query, which is a query for a specific page in a site. It is unique in that it can take query variables unlike Gatsby’s static queries.
The first step in displaying the description will be ensuring you have one to begin with.
A simple index page (
src/pages/index.js) can be marked up like so:
The first thing to do is import
graphql from Gatsby. At the top of
HomePage component declaration, export a new constant called
query. The name of the constant isn’t important, as Gatsby looks for an exported
graphql string from the file rather than a specific variable. Note that you can only have one page query per file.
Then, set the const variable’s value to be a
graphql tagged template with the query between two backticks:
The first part of writing the GraphQL query is including the operation (in this case ”
query”) along with a name.
From browsing GraphiQL, you’ll find that one of the fields that you can query on is
site, which in turn has its own
siteMetadata fields that correspond to the data provided in
Putting this together, the completed query looks like:
To start, update the
HomePage component to destructure
data from props.
data prop contains the results of the GraphQL query, and matches the shape you would expect. With this in mind, the updated
HomePage markup looks like:
gatsby develop, your home page will now display “This is where I write my thoughts.” from the description set in
graphql is a tag function. Behind the scenes Gatsby handles these tags in a particular way:
During the Gatsby build process, GraphQL queries are pulled out of the original source for parsing.
The longer answer is a little more involved: Gatsby borrows a technique from
Relay that converts your source code into an abstract syntax tree (AST) during the build step.
query-compiler.js pick out your
graphql-tagged templates and effectively remove them from the original source code.
More information about how queries work is included in the Gatsby Internals section of the docs.
This means that the
graphql tag. However, it’s possible to pass variables into page queries with the
context object when creating pages.
Variables can be added to page queries (but not static queries) through the context object that is an argument of the
Consider the following query:
MdxBlogPost query will return an MDX node in a site where
gatsby-plugin-mdx is installed and
.mdx files have been sourced with
gatsby-source-filesystem, so long as it matches the argument passed in for a
title equaling (
eq) the string
"Using a Theme".
In addition to hardcoding an argument directly into the page query, you can pass in a variable. The query can be changed to include a variable like this:
When a page is created dynamically from this blog post template in
gatsby-node.js, you can provide an object as part of the page’s context. Keys in the context object that match up with arguments in the page query (in this case:
"title"), will be used as variables. Variables are prefaced with
$, so passing a
title property will become
$title in the query.
For more information, check out the docs on creating pages programmatically.