Basics on querying the GraphQL API
Here you will find the basics you need to get started with the Prismic GraphQL API. The API has a predefined query field to retrieve documents of any type. It also offers predefined query fields for every custom type in your repository. Here we will learn the basics for both of these and more.
The _allDocuments query field will help you retrieve all the published documents in the repository. For example, this query will list the id of all your documents:
query{
_allDocuments{
edges{
node{
_meta{
id
}
}
}
}
}
If you want to get data from specific fields in your custom type, you will need to specify the fields you want to retrieve based on the custom type.
In this example we are querying all the documents in the repository. These will all display their types and ids. But for any document of the type "Blog" we will also get the title field. To achieve this, we need to use a union type switch: ... on Blog.
query{
_allDocuments{
edges{
node{
... on Blog{
title
}
_meta{
id
type
}
}
}
}
}
You can also use more than one union type switch to specify the fields you want from different types. In this example we get the id and type from all document types, as well as the title field from the Blog type, and the description field from the Page type.
query{
_allDocuments{
edges{
node{
... on Blog{
title
}
... on Page{
description
}
_meta{
id
type
}
}
}
}
}
For every custom type in your Prismic repository, the GraphQL API has two predefined query fields: one to query a single document and another to query a set of documents. For each operation you need to specify which fields you want to retrieve and a set of arguments to filter the results.
To query one particular document of a given type, you have a predefined query field that you can use. You will need to pass the uid of your document as well as its lang.
For example, if you want to get the title and the subtitle of the landing page that has the UID value of "powered-by-prismic" in the "en-us" language, you will use the following request:
query{
landing_page(uid:"powered-by-prismic", lang:"en-us"){
title
subtitle
}
}
The GraphQL API also provides a query field to get all documents of a given custom type. For example, if you want to query all the Landing Page documents from your repo, you can use the allLanding_pages query field.
Here is an example that will get the title and the subtitle of all your Landing Pages:
query{
allLanding_pages{
edges{
node{
title
subtitle
}
}
}
}
GraphQL Autocomplete
You can find all available query fields in your API Explorer by using the autocomplete with CTRL+SPACE.
GraphQL lets you perform multiple operations (queries) in one request. To do this, simply add all your operations to the query object.
For example, if you want to query your all your Blog and Page documents, you will perform the operations like this:
query{
allBlogs{
edges{
node{
title
}
}
}
allPages{
edges{
node{
summary
}
}
}
}
In the case above, you will get the results in two different objects: allBlogs will contain all your Blog documents and allPages will contain all your Page documents.
You can also access your Slice content when using the GraphQL API. You just need to specify the data you need for each slice. This is done through a Union type that specifies each slice type you want.
In the following example, the slice zone body has two different types of slices: one that is a simple text block and another one that is an image gallery. This will retrieve the "text" field in the text_block slices and the array of "image" and "caption" fields from the repeatable section of the image_gallery slices.
query{
allPosts{
body{
... on PostBodyText_block{
type
primary{
text
}
}
... on PostBodyImage_gallery{
type
fields{
image
caption
}
}
}
}
}
You can find more information and examples about this in the Retrieve Slice Content page.
On queries that return multiple results you can use different types of arguments to filter the documents that are returned. These are separated into two main places:
- First-level arguments which are filters on Meta information of the documents (id, uid, publication dates, etc.)
- The where argument lets you filter on content fields in your custom type (title, subtitle, etc.)
Examples of both of these are provided below.
In this example, we are querying the Landing Page documents with the locale (lang) of "en-us".
query{
allLanding_pages(lang:"en-us"){
edges{
node{
title
subtitle
}
}
}
}
Here is the list of first level arguments on which you can query:
id
String
The document ID
id_in
Array of strings
An array of document ids
uid
String
The UID value of a document. Note: doesn't work when using _allDocuments.
uid_in
Array of strings
An array of UID values. Note: doesn't work when using _allDocuments.
lang
String
The locale of the document
tags
String or Array of Strings
A tag or tags associated with the document
tags_in
Array of strings
An array of possible tags associated with the document
type
String
The Custom Type of the document. Note: only useful when using _allDocuments.
type_in
Array of strings
An array of possible Custom Types of the documents. Note: only useful when using _allDocuments.
similar
Object
Give an object with id of a document and the similarity max, and this will return similar documents. Read more about this on the Query similar documents page.
firstPublicationDate
String
The timestamp of when the document was first published (example: "2016-09-12T08:56:51+0000")
firstPublicationDate_after
String
This will return all the documents first published after the specified timestamp (example: "2016-09-12T08:56:51+0000")
firstPublicationDate_before
String
This will return all the documents first published before the specified timestamp (example: "2016-09-12T08:56:51+0000")
lastPublicationDate
String
The timestamp of when the document was last published/updated (example: "2016-09-12T08:56:51+0000")
lastPublicationDate_after
String
This will return all the documents last published/updated after the specified timestamp (example: "2016-09-12T08:56:51+0000")
lastPublication_before
String
This will return all the documents last published/updated before the specified timestamp (example: "2016-09-12T08:56:51+0000")
fulltext
String
This will perform a fulltext search for a specified string value
To filter your document list based on the value of specific custom field, you need to use the where argument.
In this example we are querying the title and subtitle of our Landing Pages where the "is_featured" field has the value "yes":
query{
allLanding_pages(where:{is_featured:"yes"}){
edges{
node{
title
subtitle
}
}
}
}
You can read our other documentation pages to learn more about how to query based on UID or ID, tags, dates, and fulltext search.
The results retrieved from the Prismic repository will automatically be paginated. By default the graphQL API returns 20 documents.
You can provide a sortBy argument for every generated field in the schema. Each field will provide you with either an ASC (ascending order) or DESC (descending order) option.
Here is an example that sorts the Landing Pages by their first publication date in ascending order:
query{
allLanding_pages(sortBy:meta_firstPublicationDate_ASC){
edges{
node{
title
}
}
}
}
You can read more about this on the Order your results page.
Prismic offers a cursor-based pagination as described in the GraphQL documentation:
"There are a number of ways we could do pagination, but have found that cursor-based pagination to be the most powerful amongst those available. This especially true if the cursors are opaque, either offset or ID-based pagination can be implemented using cursor-based pagination (by making the cursor the offset or the ID), and using cursors gives additional flexibility if the pagination model changes in the future."
You can read more about this on the Paginate your results page.