Retrieve the document object

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

There are two different types of queries you can run with the Prismic/Gatsby GraphQL API. One that will return a single document and another that can return multiple documents. We will go over how to get to the document level of the response in both cases.

When querying a single document

There are certain queries you can run to retrieve a single document for a given Custom Type. These queries exclude the edges and node fields and will return the document object directly.

If you don't know what the edges or node fields are, don't worry. This will make more sense when you look at the two examples below.

An example query

Here is an example of this type of query. In this case we are querying a document of the "blog_post" type. To learn more about this, check out our Query a single document page.

Copy
query {
  prismic {
    blog_post(uid: "sample-blog-post", lang: "en-us") {
      title
      publication_date
      _meta {
        uid
      }
    }
  }
}

An example response

Here is an example of the type of response returned with this type of query:

Copy
{
  "data": {
    "prismic": {
      "blog_post": {
        "title": [
          {
            "type": "heading1",
            "text": "Sample Blog Post",
            "spans": []
          }
        ],
        "publication_date": "2018-01-22",
        "_meta": {
          "uid": "sample-blog-post"
        }
      }
    }
  }
}

Note here how the document fields (title, publication_date, etc.) appear directly below the blog_post field.

Retrieve the document object

Here is a full example of a page component to get a feel for how to retrieve and display the document object:

Copy
import React from 'react'
import { graphql } from 'gatsby'
import { RichText } from 'prismic-reactjs'

const BlogPost = ({ data }) => {
  const document = data.prismic.blog_post
  if (!document) return null
	
  return (
    <>
      <h1>{RichText.asText(document.title)}</h1>
      <span>{document.publication_date}</span>
    </>
  )
}

export const query = graphql`
query {
  prismic {
    blog_post(uid: "sample-blog-post", lang: "en-us") {
      title
      publication_date
      _meta {
        uid
      }
    }
  }
}
`

export default BlogPost

NOTE: You need to add a validation that will check if the response is valid. If not, you need to return null: if (!document) return null. This check will prevent your application from breaking during the website build. Read more about this in the Adding a validation check section further down this article.

When querying multiple documents

If you don't run a query like the one discussed above, then you can retrieve more than one document. These types of queries will include the edges and node fields.

Note that you might still return only one document with this type of query. The important thing to note about this is that the query and response include the "edges" and "node" fields.

An example query

Here is an example of this type of query. In this case we are querying for all the documents with the API ID of "blog_post":

Copy
query {
  prismic {
    allBlog_posts {
      edges {
        node {
          title
          publication_date
          _meta {
            uid
          }
        }
      }
    }
  }
}

An example response

Here is an example of the response that might be returned with this type of query. In this case there are two documents returned:

Copy
{
  "data": {
    "prismic": {
      "allBlog_posts": {
        "edges": [
          {
            "node": {
              "title": [
                {
                  "type": "heading1",
                  "text": "Sample Blog Post",
                  "spans": []
                }
              ],
              "publication_date": "2018-01-22",
              "_meta": {
                "uid": "sample-blog-post"
              }
            }
          },
          {
            "node": {
              "title": [
                {
                  "type": "heading1",
                  "text": "Another Sample Post",
                  "spans": []
                }
              ],
              "publication_date": "2018-01-29",
              "_meta": {
                "uid": "another-sample-post"
              }
            }
          }
        }
      ]
    }
  }
}

You can see that in this case, the edges and node fields are returned in the response. Even if only one document is returned you will see these fields.

Retrieve the document object

As shown in the response above, the edges field is an array of objects that include the node field. You can either select the document you need from the array, or loop through this array to retrieve all the document objects.

Here is an example that retrieves and displays the first document object of the response:

Copy
import React from "react"
import { graphql } from "gatsby"
import { RichText } from "prismic-reactjs"

const BlogPost = ({ data }) => {
  const prismicContent = data.prismic.allBlog_posts.edges[0]
  if (!prismicContent) return null
  const document = prismicContent.node

  return (
    <>
      <h1>{RichText.asText(document.title)}</h1>
      <span>{document.publication_date}</span>
    </>
  )
}

export const query = graphql`
query {
  prismic {
    allBlog_posts {
      edges {
        node {
          title
          publication_date
          _meta {
            uid
          }
        }
      }
    }
  }
}
`

export default BlogPost

NOTE: You need to add a validation that will check if the response is valid. If not, you need to return null: if (!prismicContent) return null. This check will prevent your application from breaking during the website build. Read more about this in the Adding a validation check section further down this article.

Loop through multiple document objects

Here is an example that retrieves and loops through multiple document objects of the response:

Copy
import React from 'react'
import { graphql } from 'gatsby'
import { RichText } from 'prismic-reactjs'

const BlogPost = ({ data }) => {
  const prismicContent = data.prismic.allBlog_posts.edges[0]
  if (!prismicContent) return null
  const edges = data.prismic.allBlog_posts.edges

  return (
    <div>
      {edges.map(edge => {
        const document = edge.node
        return (
          <>
            <h1>{RichText.asText(document.title)}</h1>
            <span>{document.publication_date}</span>
          </>
        )
      })}
    </div>
  )
}

export const query = graphql`
query {
  prismic {
    allBlog_posts {
      edges {
        node {
          title
          publication_date
          _meta {
            uid
          }
        }
      }
    }
  }
}
`

export default BlogPost

NOTE: You need to add a validation that will check if the response is valid. If not, you need to return null: if (!prismicContent) return null. This check will prevent your application from breaking during the website build. Read more about this below.

Adding a validation check

If you have configured the plugin to enable Previews you will need to add a validation just before saving and rendering the retrieved data. This check will prevent your application from breaking during the website build.

You'll need to ensure that the retrieved data response is valid and if not, return null. This example shows how it can be done.

Copy
const prismicContent = data.prismic.allBlog_posts.edges[0]
if (!prismicContent) return null

const document = prismicContent.node

Even if your project doesn't use the Preview functionality, we recommend putting these validations in place. This way if enable Previews in the future, your components will be ready and your project won't break on build.