GraphQL Queries

The primary means of interacting with a GraphQL API from the client is a query, which is a declarative expression of data requirements from the server. Consider the following example GraphQL query, which in Gatsby returns the title of the Gatsby site from its metadata:

{
  site {
    siteMetadata {
      title
    }
  }
}

Gatsby’s internal GraphQL API will return the following response to this query:

{
  "data": {
    "site": {
      "siteMetadata": {
        "title": "A Gatsby site!"
      }
    }
  },
  "extensions": {}
}

Notice how the GraphQL query and response are structurally identical: they share the same hierarchy and the same sequence of names. In other words, a typical GraphQL query issued by a client outlines the shape that the GraphQL response issued by the server should take. The pseudo-JSON structure of the GraphQL query becomes a valid JSON object in the GraphQL response.

The preceding GraphQL query is anonymous; it lacks an explicit name. But in GraphQL, you can identify queries with an operation type and an operation name. In the following example, query is the operation type, and GetSiteInfo is the operation name:

query GetSiteInfo {
  site {
    siteMetadata {
      title
    }
  }
}

You can also identify the operation type but leave off an operation name, if you wish to write an anonymous query. This query and the previous one return an identical response:

query {
  site {
    siteMetadata {
      title
    }
  }
}

GraphQL Fields

Let’s take another look at the anonymous version of the query from the previous section:

{
  site {
    siteMetadata {
      title
    }
  }
}

In GraphQL, each of the words contained within the query (site, siteMetadata, title) that identify inner elements are known as fields. Those fields located at the top level (e.g., site) are occasionally referred to as root-level fields, but keep in mind that all GraphQL fields behave identically, and there is no functional difference between fields at any point in a query’s hierarchy.

GraphQL fields are crucial because they indicate to the GraphQL API what information is desired by the client for further processing and rendering. In GraphQL APIs outside Gatsby, the client and server are generally distinct from an architectural perspective. In Gatsby, however, the GraphQL server and client are contained within the same framework; for our purposes, React and Gatsby components are our GraphQL clients.

Fields can take aliases, which allow us to arbitrarily rename any GraphQL field in the schema to something else in the resulting response from the API. In the following example, though the title field is identified as such in the schema, we’ve aliased it to siteName in our query, so the server will return a JSON object containing siteName as the identifier rather than title:

{
  site {
    siteMetadata {
      siteName: title
    }
  }
}

Aliases can be particularly useful when you wish to serve the same data multiple times but in a different form, since GraphQL prohibits repeating the same field name twice in a single query:

{
  defaultSite: site {
    siteMetadata {
      title
    }
  }
  aliasedSite: site {
    metadata: siteMetadata {
      siteName: title
    }
  }
}

GraphQL Arguments

In GraphQL, arguments are used to apply certain criteria to the fields in the response. These can be as simple as sort criteria, such as ascending or descending alphabetical order, or as complex as date formatters, which return dates according to the format stipulated by an argument applied to a field.

Let’s take a look at a more complex query to understand how to refine the sort of response that comes back through arguments applied to fields—we’ll discuss many of the unfamiliar aspects of this query in subsequent chapters:

query {
  site {
    siteMetadata {
      title
    }
  }
  allMarkdownRemark {
    nodes {
      excerpt
      fields {
        slug
      }
      frontmatter {
        date(formatString: "MMMM DD, YYYY")
        title
        description
      }
    }
  }
}

In this anonymous query, we see an example of an argument on the date field, named formatString:

date(formatString: "MMMM DD, YYYY")

In many databases and servers, dates are stored as Unix timestamps or in a machine-friendly format rather than a human-readable format. To display a date like 2021-11-05 in a more user-friendly form in the response, we can use a GraphQL argument on the date field to perform query-time date formatting. In this example, the date would be formatted as:

"November 5, 2021"

In addition to providing a date format to the formatString argument on the date field, we can also define a locale to adapt the outputted date to the preferred locale or language, which will have different names for months and days of the week. For example:

date(
  formatString: "D MMMM YYYY"
  locale: "tr"
)

Because tr represents the Turkish language and region, our date will have the Turkish name for the month of November (note that we’ve also supplied a formatString appropriate to the region):

"5 Kasım 2021"

As mentioned previously, aliases allow us to serve multiple dates in different formats in the same response without running afoul of GraphQL’s prohibition of repeated field names in a single query:

englishDate: date(formatString: "MMMM DD, YYYY")
turkishDate: date(
  formatString: "D MMMM YYYY",
  locale: "tr"
)

You can also use fromNow, which returns a string showing how long ago or how far in the future the returned date is from the current time, and difference, which returns the difference between the date and current time in the specified unit (e.g., days or weeks):

firstDate: date(fromNow: true)
secondDate: date(difference: "weeks")

Though string formatters are a common type of argument found in GraphQL APIs, other arguments influence not only the field they are attached to but also all fields nested within. For instance, given a query that returns multiple objects of a given type, GraphQL arguments exist that allow you to arbitrarily limit, skip, filter, or sort the objects returned in the response.

{
  allMarkdownRemark(limit: 4) {
    edges {
      node {
        frontmatter {
          title
        }
      }
    }
  }
}

{
  allMarkdownRemark(limit: 4, skip: 5) {
    edges {
      node {
        frontmatter {
          title
        }
      }
    }
  }
}

{
  allMarkdownRemark(
    filter: {
      frontmatter: {
        title: {
          ne: ""
        }
      }
    }
  ) {
    edges {
      node {
        frontmatter {
          title
        }
      }
    }
  }
}

allMarkdownRemark(
  filter: {
    frontmatter: {
      title: {
        eq: "Their Eyes Were Watching God"
      }
      date: {
        ne: ""
      }
    }
  }
)

allMarkdownRemark(
  filter: {
    frontmatter: {
      title: {
        regex: "/Watching/"
        ne: "Their Eyes Were Watching God"
      }
    }
  }
)

allMarkdownRemark(
  sort: {
    fields: [frontmatter___title]
    order: ASC
  }
) {
  edges {
    node {
      frontmatter {
        title
        date
      }
    }
  }
}

allMarkdownRemark(
  sort: {
    fields: [frontmatter___title, frontmatter___date]
    order: ASC
  }
) {
  edges {
    node {
      frontmatter {
        title
        date
      }
    }
  }
}

allMarkdownRemark(
  sort: {
    fields: [frontmatter___title, frontmatter___date]
    order: [ASC, DESC]
  }
) {
  edges {
    node {
      frontmatter {
        title
        date
      }
    }
  }
}

GraphQL Query Variables

Though GraphQL query arguments are common for typical limit, skip, filter, and sort operations, GraphQL also provides a mechanism for developers to introduce query variables at the root level of the query. This is particularly useful for situations where a user defines how a list should be sorted or filtered, or what items in the list should be skipped. In short, query variables allow for us to provide user-defined arguments as opposed to static arguments that don’t change.

Consider the following example query, which leaves it up to the query variables to determine how the results should be limited and filtered:

query GetAllPosts(
  $limit: Int
  $sort: MarkdownRemarkSortInput
  $filter: MarkdownRemarkFilterInput
) {
  allMarkdownRemark {
    edges {
      node {
        frontmatter {
          title
        }
      }
    }
  }
}

In order for this query to function properly, we need to provide values for each of these query variables in the form of a JSON object containing each of these variable names:

{
  "limit": 4,
  "sort": {
    "fields": "frontmatter___title",
    "order": "ASC"
  },
  "filter": {
    "frontmatter": {
      "title": {
        "regex": "/Watching/"
      }
    }
  }
}

As you can see, query variables can take the place of query arguments when we need to provide arbitrarily defined limits, skips, filters, and sorts. Note, however, that the query must be named and cannot remain anonymous when using query variables.

GraphQL Directives

GraphQL query variables allow us to designate arbitrary arguments that apply to fields, but what if we want to define actual logic that conditionally includes or excludes certain fields at query time based on those query variables? For that we need directives. GraphQL makes two directives available:

• The @skip directive indicates to GraphQL that based on a Boolean value defined by a query variable, the field carrying the directive should be excluded from the response.

• The @include directive indicates to GraphQL that based on a Boolean value defined by a query variable, the field carrying the directive should be included in the response.

Consider the following example query, which defines a query variable $includeDate with a default value of false. If the query variable is set to true, then the response to the query will include items that have dates as well as titles:

query GetAllPosts(
  $includeDate: Boolean = false
) {
  allMarkdownRemark {
    edges {
      node {
        frontmatter {
          title
          date @include(if: $includeDate)
        }
      }
    }
  }
}

The @skip directive works similarly and is useful for cases where you want to to leave out certain information, such as when rendering solely item titles for a list view rather than the full item for the individual item view:

query GetAllPosts(
  $teaser: Boolean = false
) {
  allMarkdownRemark {
    edges {
      node {
        frontmatter {
          title
          date @skip(if: $teaser)
        }
      }
    }
  }
}

GraphQL directives are particularly useful for situations where you wish to perform conditional rendering of only certain data pertaining to a component, and when you prefer not to overload GraphQL API responses to keep payload sizes small. The @skip and @include directives can be added to any field, as long as the query variable is available.

GraphQL Fragments

Sometimes our GraphQL queries can become overly verbose, with multiple hierarchical levels and many identified fields. This often necessitates the extraction of certain parts of the query into separate, reusable sets of fields that can be included where needed in a more concise form. In GraphQL, these repeatable sets of fields are known as fragments.

Consider a scenario where we want to reuse the frontmatter portion of the following query, shown in bold, in other queries:

query {
  site {
    siteMetadata {
      title
    }
  }
  allMarkdownRemark {
    nodes {
      excerpt
      fields {
        slug
      }
      frontmatter {
        date(formatString: "MMMM DD, YYYY")
        title
        description
      }
    }
  }
}

To define this as a fragment, we can separate out the portion of the query we wish to turn into a reusable field collection and identify it as a fragment separately from the query. In addition, we can then include the fragment within a query by referring to the name we give it when we define the fragment:

query {
  site {
    siteMetadata {
      title
    }
  }
  allMarkdownRemark {
    nodes {
      excerpt
      fields {
        slug
      }
      ...MarkdownFrontmatter
    }
  }
}

fragment MarkdownFrontmatter on MarkdownRemark {
  frontmatter {  
    date(formatString: "MMMM DD, YYYY")
    title
    description
  }
}

As you can see in this example, to use our newly created fragment within the query, we simply reference it with an ellipsis prefix (...) and the name of the fragment (MarkdownFrontmatter). Now we can potentially reuse this fragment in any other query where we need the same data to be extracted.

Fragments can also be inline, where we provide the fragment’s contents directly where the fragment is invoked. The following query is identical to the previous one, and the ellipsis here represents an anonymous fragment that is defined immediately rather than in a separate fragment definition. This approach allows you to include fields by type without resorting to the use of a fragment outside the query itself, which can improve readability:

query {
  site {
    siteMetadata {
      title
    }
  }
  allMarkdownRemark {
    nodes {
      excerpt
      fields {
        slug
      }
      ... on MarkdownRemark {
        frontmatter {  
          date(formatString: "MMMM DD, YYYY")
          title
          description
        }
      }
    }
  }
}

But there’s an outstanding question that we need to answer: what exactly is the MarkdownRemark name that comes after the fragment name, if included, and the keyword on in the fragment definition? To answer that question, we need to dig a little deeper into GraphQL’s inner workings and take a look at schemas and types.

GraphQL Schemas and Types

Because GraphQL queries are fundamentally about retrieving data that adheres to a shape desired by the client, those writing queries need to have some awareness of what shapes the GraphQL API can accept. Just like databases, GraphQL has an internal schema that assigns types to fields. These types dictate what responses look like for a given field. Most GraphQL schemas are manually written by architects, but Gatsby infers a GraphQL schema based on how it handles data internally and how it manages data from external sources.

A GraphQL schema consists of a series of type definitions that define what a field returns in the form of an object (e.g., a string, a Boolean, or an integer), as well as possible arguments for that object (e.g., ASC or DESC for ascending or descending sort order, respectively). For example, consider a GraphQL response that looks like this:

{
  "title": "Good trouble"
}

In the associated GraphQL schema to which all fields adhere, the type for the title field would be identified as follows—this explicitly limits the type of object issued by the GraphQL API in response to the title field to be a string and nothing else:

title: String

Let’s take another look at the query and fragment we wrote in the previous section:

query {
  site {
    siteMetadata {
      title
    }
  }
  allMarkdownRemark {
    nodes {
      excerpt
      fields {
        slug
      }
      ...MarkdownFrontmatter
    }
  }
}

fragment MarkdownFrontmatter on MarkdownRemark {
  frontmatter {  
    date(formatString: "MMMM DD, YYYY")
    title
    description
  }
}

In this fragment definition, we’re also indicating under which field types the fragment can be applied. In this case, the allMarkdownRemark field accepts inner fields of type MarkdownRemark. Because the excerpt, fields, and frontmatter fields are all represented as possible fields within the MarkdownRemark type, we know that our fragment containing a top-level frontmatter field will be applicable for all objects of type MarkdownRemark. Every fragment must have an associated type so that a GraphQL API can validate whether that fragment can be interpreted correctly or not.

But how do we introspect our GraphQL schema to understand how types relate to one another in type definitions, like the relationship between MarkdownRemark and the fields excerpt, fields, and frontmatter? And how do we know what type each individual field is within a given GraphQL query? To answer those questions, we’ll explore the foundational role GraphQL plays in Gatsby and how Gatsby makes available GraphQL tooling that offers query debugging and schema introspection capabilities.

GraphiQL

There’s no requirement to install a GraphQL dependency or otherwise configure GraphQL when you start implementing a Gatsby site. As soon as you run gatsby develop or gatsby build at the root of your codebase, Gatsby will automatically infer and create a GraphQL schema. Once the site is compiled by running gatsby develop, you can explore Gatsby’s data layer and GraphQL API by navigating to the URL https://localhost:8000/___graphql (note the three underscores).

To see this in action, clone a new version of the Gatsby blog starter and run gatsby develop. Once the development server is running, navigate to https://localhost:8000/___graphql:

$ gatsby new gtdg-ch4-graphiql gatsbyjs/gatsby-starter-blog
$ cd gtdg-ch4-graphiql
$ gatsby develop

At this URL, you’ll see a two-sided user interface consisting of a query editor on the lefthand side and a response preview pane on the righthand side (Figure 4-1). This is GraphiQL, an interactive GraphQL query editor that allows developers to quickly test queries. Figure 4-1 also shows the Documentation Explorer, accessed by clicking “Docs,” expanded.

Figure 4-1. GraphiQL, an interactive GraphQL query editor for testing and debugging queries according to a given schema

To see GraphiQL in action, let’s try inserting a simple GraphQL query to extract some information about the site:

{
  site {
    siteMetadata {
      title
      description
    }
  }
}

After the description field, try hitting the Enter key and typing Ctrl-Space or Shift-Space. You’ll see an autocomplete list appear with fields that are valid for insertion at that point, including author and siteUrl (Figure 4-2). This autocomplete feature is one way to insert fields into GraphiQL; you can also enter them manually.

Figure 4-2. GraphiQL’s autocomplete feature can be activated at any point by typing Ctrl-Space (or Shift-Space) to see what fields can be inserted at that point in the query

Now, type Ctrl-Enter to run the query (or click the Play button in the header). You’ll see the response in the righthand pane, expressed in valid JSON (Figure 4-3). As you can see, GraphiQL will run the query against Gatsby’s internal GraphQL schema and return a response based on that schema. Testing our queries with GraphiQL, therefore, gives us full confidence that queries running correctly there will work properly within our code as well.

Figure 4-3. To run a GraphQL query in GraphQL, click the Play button or press Ctrl-Enter; you’ll see the response in the preview pane

The Documentation Explorer on the right is GraphiQL’s internal schema introspection system, which allows you to search the GraphQL schema and to view what types are associated with certain fields. The information served by the Documentation Explorer matches the information displayed when you hover over a field in the query editor on the lefthand side. To open the Documentation Explorer while it is toggled closed, click the “Docs” link in the upper righthand corner of GraphiQL.

GraphiQL Explorer

Packaged with GraphiQL’s query editor is GraphiQL Explorer, a convenient introspection interface for developers to see what fields are available for a given query, along with nested fields within them. You can also use GraphiQL Explorer to construct a query by clicking on available fields and inputs, rather than writing out the query by hand. For developers who prefer more of a graphical query building experience, GraphiQL Explorer is a convenient tool (see Figure 4-4).

Figure 4-4. In GraphiQL Explorer, built into the GraphiQL interface, you can click on fields represented in the Explorer view to construct queries without typing them by hand

GraphiQL Explorer is particularly useful for advanced queries that require complex logic—especially unions, which are generally left up to the GraphQL implementation and lack a unified standard, and inline fragments, which can be frustrating for developers new to GraphQL to work with. GraphiQL Explorer lists all the available union types within the Explorer view and makes it easy to test inline fragments.

Gatsby also includes support for code snippet generation based on GraphiQL Explorer through GraphiQL’s Code Exporter. Rather than generating just the GraphQL query, which needs to be integrated with a Gatsby component, the Code Exporter is capable of generating a Gatsby page or component file based on a query constructed in GraphiQL Explorer.

GraphQL Playground

Though GraphiQL is useful for most developers’ requirements, sometimes it’s important to have a more fundamental understanding of a GraphQL schema, at the level of how data is served to the schema by external data sources through source plugins. Exploring how schemas are constructed for GraphQL can help identify deeper-seated issues that require work within external data sources rather than within the schema itself.

GraphQL Playground, developed by Prisma, is an integrated development environment (IDE) for GraphQL queries that provides much more power than GraphiQL. It considers the logic of how data enters GraphQL schemas, rather than just allowing query testing like GraphiQL, but it requires installation and isn’t available out of the box in Gatsby. GraphQL Playground provides a range of useful tools, but for the time being it remains an experimental feature in Gatsby.

To use GraphQL Playground with Gatsby, add the GATSBY_GRAPHQL_IDE flag to the value associated with the develop script in your Gatsby site’s package.json file:

"develop": "GATSBY_GRAPHQL_IDE=playground gatsby develop",

"develop": "cross-env GATSBY_GRAPHQL_IDE=playground gatsby develop",

Now, instead of running gatsby develop, run the following command, and when you visit the URL https://localhost:8000/___graphql you’ll see the GraphQL Playground interface instead of GraphiQL (Figure 4-5):

$ npm run develop

Figure 4-5. The initial state of GraphQL Playground when you enable it in Gatsby

Now that you have a solid understanding of the available developer tools for working with GraphQL in Gatsby, we can finally turn our attention to Gatsby’s page and component queries, the most important GraphQL building blocks in Gatsby.

GATSBY_GRAPHQL_IDE=playground

Page Queries

In Gatsby, pages can be rendered using no data at all (if the data is hardcoded) or using data brought in via GraphQL queries. GraphQL queries in Gatsby pages are known as page queries, and they have a one-to-one relationship with a given Gatsby page. Unlike Gatsby’s static queries, which we’ll examine in the following sections, page queries can accept GraphQL query variables like those we saw earlier in this chapter.

Gatsby makes available a graphql tag for arbitrary GraphQL queries defined within a Gatsby page or component. To see this in action, let’s create a new Gatsby blog based on the Gatsby blog starter. Because it already comes with a source plugin enabled, we can jump right in and look at some of the GraphQL queries contained in its pages:

$ gatsby new gtdg-ch4-graphql gatsbyjs/gatsby-starter-blog
$ cd gtdg-ch4-graphql

Open src/pages/index.js, one of our Gatsby pages, and let’s go through it step by step:

import React from "react"
import { Link, graphql } from "gatsby" 

import Bio from "../components/bio"
import Layout from "../components/layout"
import SEO from "../components/seo"

const BlogIndex = ({ data, location }) => { 
  const siteTitle = data.site.siteMetadata?.title || `Title`
  const posts = data.allMarkdownRemark.nodes

  if (posts.length === 0) {
    return (
      <Layout location={location} title={siteTitle}>
        <SEO title="All posts" />
        <Bio />
        <p>
          No blog posts found. Add markdown posts to "content/blog" (or the
          directory you specified for the "gatsby-source-filesystem" plugin in
          gatsby-config.js).
        </p>
      </Layout>
    )
  }

  return ( 
    <Layout location={location} title={siteTitle}>
      <SEO title="All posts" />
      <Bio />
      <ol style={{ listStyle: `none` }}>
        {posts.map(post => {
          const title = post.frontmatter.title || post.fields.slug

          return (
            <li key={post.fields.slug}>
              <article
                className="post-list-item"
                itemScope
                itemType="http://schema.org/Article"
              >
                <header>
                  <h2>
                    <Link to={post.fields.slug} itemProp="url">
                      <span itemProp="headline">{title}</span>
                    </Link>
                  </h2>
                  <small>{post.frontmatter.date}</small>
                </header>
                <section>
                  <p
                    dangerouslySetInnerHTML={{
                      __html: post.frontmatter.description || post.excerpt,
                    }}
                    itemProp="description"
                  />
                </section>
              </article>
            </li>
          )
        })}
      </ol>
    </Layout>
  )
}

export default BlogIndex

export const pageQuery = graphql` 
  query { 
    site {
      siteMetadata {
        title
      }
    }
    allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
      nodes {
        excerpt
        fields {
          slug
        }
        frontmatter {
          date(formatString: "MMMM DD, YYYY")
          title
          description
        }
      }
    }
  }
`

This import statement brings in Gatsby’s <Link /> component and graphql tag.

Here the connection is made between our GraphQL query and the data variable, which is populated with the props generated by the response to our GraphQL query, and in the same shape as our query.

This code performs all of our rendering in JSX.

Note that we are using an export statement to ensure that Gatsby is aware of our GraphQL query. The name of the constant (here, pageQuery) isn’t important, because Gatsby inspects our code for an exported graphql string rather than a specific variable name. Many page queries in the wild are simply named query. Only one page query is possible per Gatsby page. Also note that we are using a tagged template surrounded by backticks, allowing for a multiline string that contains our GraphQL query and is indicated by Gatsby’s graphql tag. The contents of these backticks must be a valid GraphQL query in order for Gatsby to successfully populate the data in the page.

This is the GraphQL query that populates the home page of our Gatsby blog starter.

Let’s focus on that second section:

const BlogIndex = ({ data, location }) => {
  const siteTitle = data.site.siteMetadata?.title || `Title`

Rather than hardcoding data like we did in earlier chapters, we can now dig further into our data object to access all the data we need. Let’s see this in action with a simple example that pulls from our Gatsby site information in gatsby-config.js. Change the preceding lines to use our description from gatsby-config.js instead:

const BlogIndex = ({ data, location }) => {
  const siteTitle = data.site.siteMetadata?.description || `Description`

We also need to update our pageQuery GraphQL query to retrieve the site description as well as the title:

export const pageQuery = graphql`
  query {
    site {
      siteMetadata {
        title
        description
      }
    }
    allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
      nodes {
        excerpt
        fields {
          slug
        }
        frontmatter {
          date(formatString: "MMMM DD, YYYY")
          title
          description
        }
      }
    }
  }
`

Now, when you save the file and execute gatsby develop, you’ll see that the blog title has been updated to reflect the description text (“A starter blog demonstrating what Gatsby can do.”) rather than the title (“Gatsby Starter Blog”).

Page queries make up the majority of GraphQL queries you’ll construct while building rudimentary Gatsby sites. But what about GraphQL queries contained within components that aren’t pages? We’ll look at that next.

Component Queries with StaticQuery

As of Gatsby v2, Gatsby also allows individual components contained within a page to retrieve data using a GraphQL query through the StaticQuery API. This is particularly useful for situations where you’ve split out a component from a surrounding page but require external data for just that component. We call these queries component queries.

Though StaticQuery is capable of handling most of the use cases page queries already address, including fragments, static queries differ from page queries in several critical ways:

• Although page queries can accept query variables, as we’ll see later in this chapter, they do not function outside of Gatsby pages.

• Static queries cannot accept query variables (this is why they’re called “static”), but they can be used in both pages and in-page components.

• The StaticQuery API does not work properly with React.createElement invocations that fall outside of JSX’s purview. For these cases, Gatsby recommends using JSX and, if needed, explicitly using StaticQuery in a JSX element (<StaticQuery />).

Static queries share one characteristic with page queries: only one static query can be used per component, just as only one page query can be used per page. Therefore, if you have separate data requirements in another portion of the component, you will need to split that logic out into another component before adding a new static query.

Importantly, static queries provide the same benefits of co-location within components that page queries do within pages. Using the StaticQuery API allows you to both issue a query and render the data from the response in a single JSX element. Consider the following example, which demonstrates this co-location:

import React from "react"
import { StaticQuery, graphql } from "gatsby"

export default function Header() {
 return (
   <StaticQuery
     query={graphql`
       query {
         site {
           siteMetadata {
             title
           }
         }
       }
     `}
     render={data => (
       <header>
         <h1>{data.site.siteMetadata.title}</h1>
       </header>
     )}
   />
 )
}

As you can see, using the <StaticQuery /> JSX element gives us the query attribute, whose value is our component query, and the render attribute, whose value represents how we want the response data from the component query to figure into our component’s rendering within a function.

Now that we have a means of issuing component queries, not just page queries, we’re all set! But there is one outstanding question remaining, particularly for developers who have adopted the React Hooks paradigm: how can we use a React hook to define a component query rather than a JSX element?

Component Queries with the useStaticQuery Hook

As of Gatsby v2.1.0, a separate means of accessing component queries is available in the form of the useStaticQuery hook. For readers unfamiliar with the React Hooks paradigm, React hooks are methods to access state information and other key React features without having to create a class. In short, the useStaticQuery hook accepts a GraphQL query and returns the response data. It can be used in any component, including pages and in-page components.

The useStaticQuery hook does have a few limitations, just like the <StaticQuery /> JSX element:

• The useStaticQuery hook cannot accept query variables (again, this is why it is called “static”).

• Like with page queries and static queries, only one useStaticQuery hook can be used per component.

$ npm install react@^16.8.0 react-dom@^16.8.0

Let’s take another look at the example component from the previous section. This time we’ll use the useStaticQuery hook instead of the <StaticQuery /> JSX element:

import React from "react"
import { useStaticQuery, graphql } from "gatsby"

export default function Header() {
 const data = useStaticQuery(graphql`
   query {
     site {
       siteMetadata {
         title
       }
     }
   }
 `)
 return (
   <header>
     <h1>{data.site.siteMetadata.title}</h1>
   </header>
 )
}

React hooks have become popular because developers can easily use them to create chunks of repeatable functionality, much like helper functions. Because useStaticQuery is a hook, we can leverage it to compose and also recycle blocks of reusable functionality rather than invoking that functionality every time.

One common example of this is to create a hook that will provide data for reuse in any component so that the query is only issued once. This shortens the build duration and means that our Gatsby site can deploy slightly faster. For instance, we may want to only query for our site title once. In the following hook definition, we’ve created a React hook that can be reused in any component:

import { useStaticQuery, graphql } from "gatsby"

export const useSiteTitle = () => {
 const { site } = useStaticQuery(
   graphql`
     query {
       site {
         siteMetadata {
           title
         }
       }
     }
   `
 )
 return site.siteMetadata
}

Now, we can import this React hook into our header component and invoke it there to get our Gatsby site title:

import React from "react"
import { useSiteTitle } from "../hooks/use-site-title"

export default function Header() {
 const { title } = useSiteTitle()
 return (
   <header>
     <h1>{title}</h1>
   </header>
 )
}

Equipped with an understanding of page queries and component queries using either <StaticQuery /> or the useStaticQuery hook, we now have a variety of approaches to query data from within our Gatsby pages and components.