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 GraphQuery parameter

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.

Our GraphQuery example

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.

Retrieve fields at the top level of the document

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.

A single field in the document

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.

Copy

{
  blog {
    title
  }
}

Multiple fields in the document

This example will get the title, main_image, and description fields of the document of the type blog.

Copy

{
  blog {
    title
    main_image
    description
  }
}

All the fields in the document

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.

Copy

{
  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.

Retrieve fields in a group

In these examples we will show how to retrieve content fields within a Group field.

Certain fields from a group

This example will get the field1 field in the Group field named group.

Copy

{
  blog {
    group {
      field1
    }
  }
}

All the fields in a group

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.

Copy

{
  blog {
    group {
      ...groupFields
    }
  }
}

Retrieve fields in a slice

In these examples we will show how to retrieve content fields from within Slices.

Certain fields from a slice

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.

Copy

{
  blog {
    body {
      ...on text_block {
        non-repeat {
          rich_text
        }
      }
      ...on image_gallery {
        repeat {
          image
        }
      }
    }
  }
}

All fields in a slice

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.

Copy

{
  blog {
    body {
      ...on text_block {
        non-repeat {
          ...non-repeatFields
        }
      }
      ...on image_gallery {
        non-repeat {
          ...non-repeatFields
        }
        repeat {
          ...repeatFields
        }
      }
    }
  }
}

Retrieve fields in a linked document

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.

A single field from a linked document

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.

Copy

{
  blog {
    author_link {
      ...on author {
        name_of_the_author
      }
    }
  }
}

Multiple fields from a linked document

This example will get the name_of_the_author and profile_pic fields of a linked document of the type author.

Copy

{
  blog {
    author_link {
      ...on author {
        name_of_the_author
        profile_pic
      }
    }
  }
}

All fields from a linked document

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.

Copy

{
  blog {
    author_link {
      ...on author {
        ...author_Fields
      }
    }
  }
}

Fields from different types

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.

Copy

{
  blog {
    author_link {
      ...on author {
        ...author_Fields
      }
      ...on page {
        title
      }
    }
  }
}

If the Content Relationship link type is uniquely defined

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.

Copy

{
  blog {
    author_link {
      ...author_linkFields
    }
  }
}

Retrieving all the fields of a document along with linked content

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.

Copy

{
  blog {
    ...blogFields
    author_link {
      name_of_the_author
      profile_pic
    }
  }
}

Use graphQuery with Javascript

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:

Copy

npm install --save prismic-javascript@2.0.0

Then here is a simple example of how to use the graphQuery option with the prismic-javascript kit:

Copy

const mySuperGraphQuery = `{
  blog {
    field1
    field2
    author_link {
      name
    }
  }
}`

api.getByUID('blog', 'example-uid',
  { 'graphQuery': mySuperGraphQuery }
).then(function (document) {
  // document contains the document content
});

Use graphQuery with the Rest API

The URL parameter is called graphQuery. Here is the format you need to use in your query url:

Copy

&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

Copy

{
  blog {
    field1
    field2
  }
}

When we encode it using the link above and add it to our query, the query url will look like this:

Copy

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

Optimization Tips

When using GraphQuery you should be aware that request URLs to the REST API are limited to 2048 characters, including escaped characters like {.

The GraphQuery examples below show the object structures, one reduced and the other standard. You can reduce your string length by using line breaks with no spaces or tabs like:

Whitespace Removed
With Whitespace

Copy

{
blog{
title
main_image
description
author_link{
...on author{
...author_Fields
}
}
}
}

Copy

{
  blog {
    title
    main_image
    description
    author_link {
      ...on author {
        ...author_Fields
    }
  }
}

To remove whitespace from your queries you can use a white space removal tool, or trim the spaces with your chosen programing language.

Legacy support

If you already use fetch or fetchLinks in your website, don't worry — these two query options will continue to work as before.