GraphQuery (fetchLinks v2)
GraphQuery is a query option you can add to your Prismic queries to specify which fields to retrieve and what content to retrieve from Linked Documents / Content Relationships. GraphQuery use a GraphQL-like syntax, and allows you to do selective fetching (i.e. fetch only the fields you need) and deep fetching (i.e. fetch the document + author in one request).
Before Reading
It's important to keep in mind that GraphQuery is not GraphQL, it just uses a GraphQL-like syntax to choose the fields you wish to retrieve. There is currently no support for many GraphQL features such as named queries or introspection. Everything that is supported is described in the documentation below.
The new GraphQuery option will work like any other query option. When specifying your query, you just need to add the graphQuery option with your particular fields that you wish to retrieve.
The end of this article has more information on how to add this option with the REST API or if you are querying with the prismic-javascript SDK.
To help explain GraphQuery, we will use a concrete example. We will say that we are querying a custom type blog which contains simple fields like title, main_image, and description. It also has a Group field named group that contains fields named field1 and field2.
Our blog type also has a Content Relationship field name related. This field can link to either a document of the type blog or the type page. The examples below will also refer to another Content Relationship field named author_link that can link only to a document of the type author.
Finally, the blog type contains a Slice Zone named body with two slices: text_block and image_gallery.
Here is the JSON code for this Custom Type as reference.
In these examples we will show how to retrieve content fields from the top level document.
NOTE: Your GraphQueries must be created using spaces and not tabs as this can cause errors.
This example will get the title field of the document of the type blog. It will retrieve the title field only and exclude all other fields from the document object.
{
blog {
title
}
}This example will get the title, main_image, and description fields of the document of the type blog.
{
blog {
title
main_image
description
}
}This example will get all the fields in the blog document. We will accomplish this using the fragment syntax. It is done by adding ... before the name of the Custom Type and Fields after the name of the type.
{
blog {
...blogFields
}
}It is worth noting that in this case, you can accomplish the same thing by simply excluding the graphQuery option from your query.
In these examples we will show how to retrieve content fields within a Group field.
This example will get the field1 field in the Group field named group.
{
blog {
group {
field1
}
}
}This example will get all the fields in the Group field named group. We will accomplish this using the fragment syntax. It is done by adding ... before the name of the field and Fields after the name of the field.
{
blog {
group {
...groupFields
}
}
}In these examples we will show how to retrieve content fields from within Slices.
In this example we will retrieve the non-repeatable Rich Text field named rich_text in the Slice named text_block and the repeatable image field in the image_gallery slice.
{
blog {
body {
...on text_block {
non-repeat {
rich_text
}
}
...on image_gallery {
repeat {
image
}
}
}
}
}In this example we will retrieve all the non-repeatable fields from the text_block slices and all of the fields from the image_gallery slices.
{
blog {
body {
...on text_block {
non-repeat {
...non-repeatFields
}
}
...on image_gallery {
non-repeat {
...non-repeatFields
}
repeat {
...repeatFields
}
}
}
}
}These examples will show you how to retrieve content from a document of the type author through the Content Relationship/Link field named author_link.
We have to use the use a Union Type ...on to define the custom type that we are querying, in this case author. The Union Type is what allows you to do a switch based on the type of document that is linked.
In this example, the author custom type contains three fields: name_of_the_author, profile_pic, and description.
We will retrieve content from a linked document in a Content Relationship/Link field named author_link. We will get the name_of_the_author field of a linked document of the type author. In this case, the Content Relationship/Link field is named author_link inside the blog type.
{
blog {
author_link {
...on author {
name_of_the_author
}
}
}
}This example will get the name_of_the_author and profile_pic fields of a linked document of the type author.
{
blog {
author_link {
...on author {
name_of_the_author
profile_pic
}
}
}
}To get all the fields from a linked document, we will need to use the fragment syntax. It is done by adding ... before the name of the Content Relationship/Link field and Fields after the name of the field.
This example will get all of the fields of a linked document of the type author.
{
blog {
author_link {
...on author {
...author_Fields
}
}
}
}Getting all the fields from linked documents that could possibly be different types is easy because we are already using the Union type ...on.
This example will get all of the fields of a linked document of the type author and the title of a linked document of the type page.
{
blog {
author_link {
...on author {
...author_Fields
}
...on page {
title
}
}
}
}If the type of the Content Relationship/Link is uniquely defined in the constraints of your field, which you can find in the custom type builder, you will not need to use a Union Type ...on.
This example will get all the fields of a linked document of the Content Relationship/Link field named author_link inside the blog type.
{
blog {
author_link {
...author_linkFields
}
}
}In order to retrieve content from a linked document as well as all the fields from the parent document, you must use the fragment syntax on the parent document. It is done by adding ... before the name of the Custom Type and Fields after the name of the type.
{
blog {
...blogFields
author_link {
name_of_the_author
profile_pic
}
}
}We did an update of our prismic-javascript kit that supports GraphQuery. Make sure to update to at least version 2.0.0 in order to ensure that GraphQuery will work.
Here is the code that you need to run in your terminal to update your kit:
npm install --save prismic-javascript@2.0.0Then here is a simple example of how to use the graphQuery option with the prismic-javascript kit:
const mySuperGraphQuery = `{
blog {
field1
field2
author_link {
name
}
}
}`
api.getByUID('blog', 'example-uid',
{ 'graphQuery': mySuperGraphQuery }
).then(function (document) {
// document contains the document content
});The URL parameter is called graphQuery. Here is the format you need to use in your query url:
&graphQuery=<your_fields>In this case, <your_fields> are the fields you wish to retrieve from your document encoded as URL.
If you test this feature with the API Browser, we recommend encoding the query with the following tool : https://meyerweb.com/eric/tools/dencoder/
We'll walk through an example. Let's say that you want to add the following GraphQuery
{
blog {
field1
field2
}
}When we encode it using the link above and add it to our query, the query url will look like this:
https://your-repo-name.prismic.io/api/v2/documents/search?ref=WzypfygAACcAfsmc&graphQuery=%7B%0A%20%20blog%20%7B%0A%20%20%20%20field1%0A%20%20%20%20field2%0A%20%20%7D%0A%7D