Query Data

On this page, you'll learn how to query documents from your Prismic repository using the Gatsby source plugin.


Query basics

The schema of the Prismic and Gatsby plugin gives you two options to write your queries; where ${CustomType} is the API ID of your document's Custom Type:

  1. prismic${CustomType}: Queries a single document of a given type with optional filtering parameters.
  2. allPrismic${CustomType}: Queries all documents of a given type.

See the following examples:

  • prismic${CustomType}
  • allPrismic${CustomType}
prismic${CustomType}
Copy
query PageQuery ($id: String) {
  prismicPage(id: {eq: $id}) {
    data {
      document_title {
        text
      }
    }
  }
}
allPrismic${CustomType}
Copy
query BlogPostList {
  allPrismicBlogPost {
    nodes {
      data {
        document_title {
          text
        }
      }
    }
  }
}

Structure of the API response

This is the format you'll receive from the API for your single and repeatable documents. Here are truncated examples of API responses containing a few fields and one Slice.

You can find Slices inside the body array property:

  • Multiple documents
  • Single Document
Multiple documents
Copy
{
  "data": {
    "allPrismicPage": {
      "nodes": [
        {
          "data": {
            "example_date": "2020-12-10",
            "example_timestamp": "2020-12-10T04:05:09+0000",
            "example_color": "#c7ab5d",
            "example_number": 74.5,
            "example_key_text": "Example Key Text Value",
            "example_select": "North",
            "example_boolean": true,
            "body": [
              {
                "primary": {
                  "slice_type": "quote",
                  "quote": {
                    "richText": [
                      {
                        "type": "paragraph",
                        "text": "Etiam pellentesque mauris ut lectus",
                        "spans": []
                      }
                    ]
                  }
                }
              },
              // ... other Slices
            ]
          }
        },
        // ... other documents
      ]
    }
  }
}
Single Document
Copy
{
  "data": {
    "prismicHomepage": {
      "data": {
        "example_date": "2020-12-10",
        "example_timestamp": "2020-12-10T04:05:09+0000",
        "example_color": "#c7ab5d",
        "example_number": 74.5,
        "example_key_text": "Example Key Text Value",
        "example_select": "North",
        "example_boolean": true,
        "body": [
          {
            "primary": {
              "slice_type": "quote",
              "quote": {
                "richText": [
                  {
                    "type": "paragraph",
                    "text": "Etiam pellentesque mauris ut lectus",
                    "spans": []
                  }
                ]
              }
            }
          }
         // ... other Slices
        ]
      }
    }
  }
}

Save the response

Save the response from a query in a variable. We usually name it document. See the following examples:

  • Multiple documents
  • Single document
Multiple documents
Copy
const documents = data.allPrismicPages.nodes
Single document
Copy
const document = data.prismicAuthor

Create pages and routes

Create dynamic pages programmatically if your documents are repeatable or if your repository has more than one language.

Create a single page manually if your documents are singletons, for example, if you want to create a home or contact page.

The Link Resolver defines the URL routes of your application. Once you create it and declare it in the plugin options, the URL routes become available in the url field of your queries.

Fragments

Fragments are a way to break down large queries into smaller ones, making them reusable and unique to a component's code. Page queries become more clear and Slice components more modular. Everything that belongs to the Slice is in the same component file.

In Prismic, Slice components and the SliceZone are great examples of use for Fragments.

For example, look at this page query that uses fragments. Both queries work in the same way, only fragments make the code shorter and more intelligible.

  • with fragments
  • without fragments
with fragments
Copy
query pageQuery($id: String, $lang: String) {
  prismicPage(id: {eq: $id}, lang: {eq: $lang}) {
    data {
      body {
        ... on PrismicSliceType {
          id
          slice_label
          slice_type
        }
        ...PageDataBodyEmailSignup
        ...PageDataBodyFullWidthImage
        ...PageDataBodyHeadlineWithButton
        ...PageDataBodyInfoWithImage
        ...PageDataBodyTextInfo
      }
    }
  }
}
without fragments
Copy
query pageQuery($id: String, $lang: String) {
  prismicPage(id: {eq: $id}, lang: {eq: $lang}) {
    data {
      body {
        ... on PrismicSliceType {
          id
          slice_label
          slice_type
        }
        ... on PrismicPageDataBodyEmailSignup {
          id
          primary {
            section_title {
              richText
            }
          }
          slice_type
        }
        ... on PrismicPageDataBodyFullWidthImage {
          id
          primary {
            image {
              alt
              url
            }
          }
          slice_type
        }
        ... on PrismicPageDataBodyHeadlineWithButton {
          id
          primary {
            description {
              richText
            }
          }
          slice_type
        }
        ... on PrismicPageDataBodyInfoWithImage {
          id
          primary {
            text {
              richText
            }
          }
          slice_label
        }
        ... on PrismicPageDataBodyTextInfo {
          id
          primary {
            section_title {
              richText
            }
          }
          slice_type
        }
      }
    }
  }
}

When you add a fragment to a component and then import that component to a page, Gatsby and GraphQL automatically know that the fragment can be used in a page query.

More resources

If you want to learn more about fragments, here are some more resources for you to explore:


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.