<commit_before>---
title: 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](http://graphql.org/).

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

GraphQL is a **q**uery **l**anguage (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](/docs/building-with-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:

```graphql
{
  site {
    siteMetadata {
      title
    }
  }
}
```

Which returns this:

```json
{
  "site": {
    "siteMetadata": {
      "title": "A Gatsby site!"
    }
  }
}
```

A basic page component with a GraphQL query might look like this:

```jsx
import React from "react";

export default ({ data }) => (
  <div>
    <h1>About {data.site.siteMetadata.title}</h1>
    <p>We're a very cool website you should return to often.</p>
  </div>
);

export const query = graphql`
  query AboutQuery {
    site {
      siteMetadata {
        title
      }
    }
  }
`;
```

The result of the query is automatically inserted into your React component
on the `data` prop. GraphQL and Gatsby let you ask for data and then
immediately start using it.

## How to learn GraphQL

Your experience developing with Gatsby might be the first time you've seen GraphQL! We hope you love it as much
as we do and find it useful for all your projects.

When starting out with GraphQL, we recommend the following two tutorials:

* https://www.howtographql.com/
* http://graphql.org/learn/

[The official Gatsby tutorial](/tutorial/part-four/) also includes an introduction to using GraphQL specifically with Gatsby.

## How do GraphQL and Gatsby work together?

One of the great things about GraphQL is how flexible it is. People use GraphQL
with [many different programming languages](http://graphql.org/code/) and for web and native apps.

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.<commit_msg>docs: Clarify queries and Components (#4352)<commit_after>---
title: 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](http://graphql.org/).

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

GraphQL is a **q**uery **l**anguage (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](/docs/building-with-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:

```graphql
{
  site {
    siteMetadata {
      title
    }
  }
}
```

Which returns this:

```json
{
  "site": {
    "siteMetadata": {
      "title": "A Gatsby site!"
    }
  }
}
```

A basic page component with a GraphQL query might look like this:

```jsx
import React from "react";

export default ({ data }) => (
  <div>
    <h1>About {data.site.siteMetadata.title}</h1>
    <p>We're a very cool website you should return to often.</p>
  </div>
);

export const query = graphql`
  query AboutQuery {
    site {
      siteMetadata {
        title
      }
    }
  }
`;
```

The result of the query is automatically inserted into your React component
on the `data` prop. GraphQL and Gatsby let you ask for data and then
immediately start using it.

*Note:* Queries are only executed from Page or Layout components. For other
components you'll want to use GraphQL [*fragments*](#fragments).

## How to learn GraphQL

Your experience developing with Gatsby might be the first time you've seen GraphQL! We hope you love it as much
as we do and find it useful for all your projects.

When starting out with GraphQL, we recommend the following two tutorials:

* https://www.howtographql.com/
* http://graphql.org/learn/

[The official Gatsby tutorial](/tutorial/part-four/) also includes an introduction to using GraphQL specifically with Gatsby.

## How do GraphQL and Gatsby work together?

One of the great things about GraphQL is how flexible it is. People use GraphQL
with [many different programming languages](http://graphql.org/code/) and for web and native apps.

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.
{'fraction_non_alphanumeric': 0.06595113684507838, 'fraction_numerical': 0.0011297839288236125, 'mean_word_length': 3.791610284167794, 'pattern_counts': {'":': 6, '<': 15, '<?xml version=': 0, '>': 17, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5266914', 'n_tokens_mistral': 1968, 'n_tokens_neox': 1909, 'n_words': 1045}