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.

Query all Documents

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:

Copy

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.

Copy

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.

Copy

query{
  _allDocuments{
    edges{
      node{
        ... on Blog{
          title
        }
        ... on Page{
          description
        }
        _meta{
          id
          type
        }
      }
    }
  }
}

Query by Custom 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.

Query a single document

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:

Copy

query{
  landing_page(uid:"powered-by-prismic", lang:"en-us"){
    title
    subtitle
  }
}

Query multiple documents

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:

Copy

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.

Query multiple custom types

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:

Copy

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.

Access Slice data

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.

Copy

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.

Filtering Documents

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.

Filter on metadata values

In this example, we are querying the Landing Page documents with the locale (lang) of "en-us".

Copy

query{
  allLanding_pages(lang:"en-us"){
    edges{
      node{
        title
        subtitle
      }
    }
  }
}

Here is the list of first level arguments on which you can query:

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

Filter on custom field values

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":

Copy

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.

Ordering and pagination

The results retrieved from the Prismic repository will automatically be paginated. By default the graphQL API returns 20 documents.

Order your results

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:

Copy

query{
  allLanding_pages(sortBy:meta_firstPublicationDate_ASC){
    edges{
      node{
        title
      }
    }
  }
}

You can read more about this on the Order your results page.

Paginate your results

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.