All Technologies / Rest API / GraphQuery (fetchLinks v2)

GraphQuery (fetchLinks v2)

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

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.

Retrieve fields at the top level of the document

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.

Retrieve a single field

The below example illustrates how to retrieve only the Title field and exclude all other fields.

Copy
{
  blog {
    main_title
  }
}

Retrieve multiple fields

The below example will get the Title, Rich Text, and Image fields.

Copy
{
  blog {
    main_title
    main_desc
    main_image
  }
}

Retrieve all the fields

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.

Copy
{
  blog {
    ...blogFields
  }
}

Retrieve fields in a group

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

Certain fields from a group

This example will retrieve only the Rich Text field in the Group field named group.

Copy
{
  menu {
    group {
      menu_label
    }
  }
}

All the fields in a group

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.

Copy
{
  menu {
    group {
      ...groupFields
    }
  }
}

Retrieve fields in a Slice

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"

Certain fields from a Slice

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.

Copy
{
  homepage {
    body {
      ...on text_block {
        non-repeat {
          blog_title
        }
      }
      ...on image_gallery {
        repeat {
          image_caption
        }
      }
    }
  }
}

All fields in a Slice

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.

Copy
{
  homepage {
    body {
      ...on text_block {
        non-repeat {
          ...non-repeatFields
        }
      }
      ...on image_gallery {
        non-repeat {
          ...non-repeatFields
        }
        repeat {
          ...repeatFields
        }
      }
    }
  }
}

Retrieve fields from a linked document

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

Retrieve a single field from a linked document

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.
Copy
{
  blog {
    author_link {
      ...on author {
        author_name
      }
    }
  }
}

Multiple fields from a linked document

This example will retrieve multiple fields such as Title and Image with their API IDs author_name and author_image respectively.

Copy
{
  blog {
    author_link {
      ...on author {
        author_name
        author_image
      }
    }
  }
}

All fields from a linked document

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.

Copy
{
  blog {
    author_link {
      ...on author {
        ...authorFields
      }
    }
  }
}

Retrieve fields from different linked documents

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 {
        ...authorFields
      }
      ...on page {
        title
      }
    }
  }
}

If the Content Relationship link type is uniquely defined

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.

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 Custom Type.

Copy
{
  blog {
    ...blogFields
    author_link {
      author_name
      author_image
    }
  }
}

Use GraphQuery with Javascript

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:

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
  }
}

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.

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#format=json

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.

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.