Query by ID or UID

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.

This page gives examples of how to query a document either by its ID or its UID.

Query by ID

Since IDs are global fields, you will be able to find the document you want using the id argument.

Here is an example that shows how to query a document of the type Blog with the ID "XlVGThAAACUAs44p". Then we retrieve a Title field that has the API ID of "author_name" and the meta data with the id:

Copy
query myBlogQuery {
  prismic {
    allBlogs(id: "XlVGThAAACUAs44p") {
      edges {
        node {
          author_name
          _meta {
            id
          }
        }
      }
    }
  }
}

Query by UID

If you setup your Custom Type to have a UID field, you will be able to filter your results based on the UID value using the uid argument.

Here is an example that will query a document of the type Page with the UID value of "first-page". Then we retrieve a Title field that has the API ID of "author_name" and the meta data with the uid:

Copy
query myPageQuery {
  prismic {
    allPages(uid: "first-page") {
      edges {
        node {
          author_name
          _meta {
            uid
          }
        }
      }
    }
  }
}

How to query dynamically

It is common that you will need to dynamically load documents in your Gatsby website using variables. Fortunately this is pretty easy to set up. The first thing you need to do is to add your Custom Type to your Gatsby configuration.

In your gatsby-config.js file, add your Custom Type to the option.pages attribute of the gatsby-source-prismic-graphql plugin configuration and specify the routes to match this to.

Dynamically query by ID

Here's an example for Blog pages (note that the configuration below excludes other options to focus only on the parts required for this):

Copy
...
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name',
		...
    pages: [{
      type: 'Blog',
      match: '/blog/:id',
      component: require.resolve('./src/templates/blog.js'),
    }],
  }
}
...

You can see in the above example the route match includes :id. This is important as it is how the query will know which ID value to use.

Then in the src/templates/blog.js file (for this example), here's what your query would look like:

Copy
query myBlogQuery($id:String){ 
  prismic {
    allBlogs(id: $id) {
      edges {
        node {
          author_name
          _meta {
            id
          }
        }
      }
    }
  }
}
Copy

With this in place, the routes will automatically be generated based on the ID value of the blog posts.

Dynamically query by UID

Here's an example for a Custom Type with the name "Page" (note that the configuration below excludes other options to focus only on the parts required for this):

Copy
...
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name',
		...
    pages: [{
      type: 'Page',
      match: '/page/:uid',
      component: require.resolve('./src/templates/page.js'),
    }],
  }
}
...

You can see in the above example the route match includes :uid. This is important as it is how the query will know which UID value to use.

Then in the src/templates/page.js file (for this example), here's what your query would look like:

Copy
query myPageQuery($uid:String){ 
  prismic {
    allPages(id: $uid) {
      edges {
        node {
          author_name
          _meta {
            uid
          }
        }
      }
    }
  }
}

With this in place, the routes will automatically be generated based on the UID value of the page posts.