GraphQuery API Option
GraphQuery is an advanced version of fetchLinks that allows you to do selective fetching (i.e., fetch only the required fields ) and deep fetching (i.e., parent document fields + fields from the linked documents).
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 options will work like any other query option. To specifying your query, 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.
NOTE: Your GraphQueries must be created using spaces and not tabs as this can cause errors.
In these examples, we are querying a Custom Type blog that contains the following fields:
Field
API ID
Title
main_title
Rich Text
main_desc
Image
main_image
NOTE: Your GraphQueries must be created using spaces and not tabs as this can cause errors.
The below example illustrates how to retrieve only the Title field and exclude all other fields.
{
blog {
main_title
}
}{
blog {
main_title
main_desc
main_image
}
}To get all the fields from the document, use the fragment syntax. It is done by adding ... before and Fields after the name of the Custom Type.
{
blog {
...blogFields
}
}In these examples, we are querying a Custom Type menu that contains the following fields:
Group field name
group
Fields inside Group field
A Rich Text field that has API ID of menu_label
A Link field that has API ID of link_to_doc
This example will retrieve only the Rich Text field in the Group field named group.
{
menu {
group {
menu_label
}
}
}This example will retrieve all the fields. We will accomplish this using fragment syntax. It is done by adding ... before and Fields after the API ID of the Group field.
{
menu {
group {
...groupFields
}
}
}In this example, we have two Slices in a homepage Custom Type: a text_block Slice and an image_gallery Slice with the following fields:
Slice name
Fields with API IDs
text_block
Primary
non-repeatable
- A Title field with the API ID of "blog_title"
Items
repeatable
-A Rich text with the API ID of "blog_desc"
image_gallery
Primary
non-repeat
-A Title field with API ID of "image_caption"
Items
repeat
-A Image field with the API ID of "blog_image"
In this example, we will retrieve the non-repeatable Title field from the text_block Slice and the repeatable Title field in the image_gallery Slice.
{
homepage {
body {
...on text_block {
non-repeat {
blog_title
}
}
...on image_gallery {
repeat {
image_caption
}
}
}
}
}In this example, we will retrieve all the non-repeatable fields from the text_block Slice and all of the fields from the image_gallery Slice.
{
homepage {
body {
...on text_block {
non-repeat {
...non-repeatFields
}
}
...on image_gallery {
non-repeat {
...non-repeatFields
}
repeat {
...repeatFields
}
}
}
}
}Let's say, you have a blog Custom Type with a Content Relationship field that has an API ID of author_link and it is linked to author Custom Type.
The author Custom Type contains the following fields:
Field
API ID
Title
author_name
Rich Text
author_desc
Image
author_image
In this example, we will retrieve a single field Title with its API ID author_name.
Things to remember
- We have to 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.
- You have to specify the API ID of the Content Relationship field to retrieve content from the linked documents. In this case, it's author_link.
{
blog {
author_link {
...on author {
author_name
}
}
}
}This example will retrieve multiple fields such as Title and Image with their API IDs author_name and author_image respectively.
{
blog {
author_link {
...on author {
author_name
author_image
}
}
}
}To get all the fields from a linked document, use the fragment syntax. It is done by adding ... before and Fields after the name of the Custom Type.
{
blog {
author_link {
...on author {
...authorFields
}
}
}
}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 {
...authorFields
}
...on page {
title
}
}
}
}If the type of the Content Relationship 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 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 Custom Type.
{
blog {
...blogFields
author_link {
author_name
author_image
}
}
}Prismic version
Make sure you use the latest version of @prismicio/client kit to ensure that GraphQuery will work. Find more detail here.
Then here is a simple example of how to use the GraphQuery option with @prismicio/client 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
}
}After encoding it and when Querying the API Browser, add it to query after the "ref" parameter and before the hashtag (#) in the URL to get filtered results.
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#format=jsonWhen 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
{
blog{
title
main_image
description
author_link{
...on author{
...author_Fields
}
}
}
}{
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.
If you already use fetch or fetchLinks in your website, don't worry — these two query options will continue to work as before.
Was this article helpful?
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.