Ecosystem

Design

Querying Data with GraphQL

There are many options for loading data into React components. One of the most
popular and powerful of these is a technology called
GraphQL.

GraphQL was invented at Facebook to help product engineers pull needed data into
React components.

GraphQL is a query language (the QL part of its name). If you’re
familiar with SQL, it works in a very similar way. Using a special syntax, you describe
the data you want in your component and then that data is given
to you.

Gatsby uses GraphQL to enable page and layout
components to declare what data they and their
sub-components need. Then, Gatsby makes that data available in
the browser when needed by your components.

Why is GraphQL so cool?

Eliminate frontend data boilerplate — no need to worry about requesting & waiting for data. Just ask for the data you need with a GraphQL query and it’ll show up when you need it

Push frontend complexity into queries — many data transformations can be done at build-time within your GraphQL queries

It’s the perfect data querying language for the often complex/nested data dependencies of modern applications

Improve performance by removing data bloat — GraphQL is a big part of why Gatsby is so fast as it enables lazy-loading the exact data in the exact form each view needs

What does a GraphQL query look like?

GraphQL lets you ask for the exact data you need. Queries look like JSON:

How do GraphQL and Gatsby work together?

Most people run GraphQL on a server to respond live to requests for
data from clients. You define a schema (a schema is a formal way of describing
the shape of your data) for your GraphQL server and then your GraphQL resolvers
retrieve data from databases and/or other APIs.

Gatsby uses GraphQL at build-time and not for live
sites. This is unique, and it means you don’t need to run additional services (e.g. a database
and node.js service) to use GraphQL for production websites.

Gatsby is a great framework for building apps so it’s possible and encouraged
to pair Gatsby’s native build-time GraphQL with GraphQL queries running against
a live GraphQL server from the browser.

Where does Gatsby’s GraphQL schema come from?

Most usages of GraphQL involve manually creating a GraphQL schema.

With Gatsby, we use plugins which fetch data from different sources. We then use that data
to automatically infer a GraphQL schema.

If you give Gatsby data that looks like this:

{"title":"A long long time ago"}

Gatsby will create a schema that looks something like this:

title: String

This makes it easy to pull data from anywhere and immediately start writing
GraphQL queries against your data.

This can cause confusion as some data sources allow you to define
a schema even when there’s not any data added for parts or all of the schema. If parts of the data haven’t been added, then those parts of the schema might not be recreated in Gatsby.

Powerful data transformations

GraphQL enables another unique feature of Gatsby — it lets you control data transformations with arguments to your queries. Some examples follow.

Formatting dates

People often store dates like “2018-01-05” but want to display the date in some other form like “January 5th, 2018”. One way of doing this is to load a date-formatting JavaScript library into the browser. Or, with Gatsby’s GraphQL layer, you can do the formatting at query-time like:

{
date(formatString:"MMMM Do, YYYY")}

Markdown

Gatsby has transformer plugins which can transform data from one form to another. A common example is markdown. If you install gatsby-transformer-remark, then in your queries, you can specify you want the transformed HTML version instead of markdown:

markdownRemark {
html
}

Images

Gatsby has rich support for processing images. Responsive images are a big part of the modern web and typically involve creating 5+ sized thumbnails per photo. With Gatsby’s gatsby-transformer-sharp, you can query your images for responsive versions. The query automatically creates all the needed responsive thumbnails and returns src and srcSet fields to add to your image element.

Combined with a special Gatsby image component, gatsby-image, you have a very powerful set of primitives for building sites with images.

Advanced

Fragments

Notice that in the above example for querying images, we used ...GatsbyImageSharpResolutions, which is a GraphQL Fragment, a reusable set of fields for query composition. You can read more about them here.

If you wish to define your own fragments for use in your application, you can use named exports to export them in any Javascript file, and they will be automatically processed by Gatsby for use in your GraphQL queries.

For example if I put a fragment in a helper component, I can use that fragment in any other query: