Fetch Data
On this page, you'll learn how to retrieve content in from your Prismic repository using the Gatsby source plugin.
The Prismic and Gatsby plugin schema gives you two options to write your queries using the API ID of your document's Custom Type (in these examples, the Custom Type’s API ID is ExampleCustomType):
- prismicExampleCustomType: Queries a single document of a given type with optional filtering parameters.
- allPrismicExampleCustomType: Queries all documents of a given type.
Here's a query for a single document:
query MyQuery ($id: String) {
prismicExampleCustomType(id: {eq: $id}) {
data {
example_title {
text
}
}
}
}
Let's break down the syntax in the above example:
- query: The GraphQL reserved word for writing a query
- MyQuery: The name of the query
- ($id: String): The variable declaration for the page ID
- prismicExampleCustomType(id: {eq: $id}): The singleton query, filtered by the ID that is provided when the query runs
- example_title: The field to return
Here's a query for all documents of a repeatable type:
query MyQuery {
allPrismicExampleCustomType {
nodes {
data {
example_title {
text
}
}
}
}
}
This syntax is similar to the singleton query. However, it uses allPrismicExampleCustomType instead of prismicExampleCustomType, and it doesn't need to filter by ID.
We recommend that you store the response in a variable called document:
- Single document
- Multiple queries
const document = data.prismicAuthor
const documents = data.allPrismicPages.nodes
Fragments are a way to break down large queries into smaller ones, making them reusable and unique to a component's code. Page queries become more transparent, and Slice components more modular. Everything that belongs to the Slice is in the same component file.
In Prismic, Slice components and the Slice Zone are great use cases for Fragments.
For example, look at this page query that uses fragments. Both queries work the same way. Only fragments make the code shorter and more legible.
- with fragments
- without fragments
query pageQuery($id: String, $lang: String) {
prismicPage(id: {eq: $id}, lang: {eq: $lang}) {
data {
body {
... on PrismicSliceType {
id
slice_label
slice_type
}
...PageDataBodyEmailSignup
...PageDataBodyFullWidthImage
...PageDataBodyHeadlineWithButton
...PageDataBodyInfoWithImage
...PageDataBodyTextInfo
}
}
}
}
query pageQuery($id: String, $lang: String) {
prismicPage(id: {eq: $id}, lang: {eq: $lang}) {
data {
body {
... on PrismicSliceType {
id
slice_label
slice_type
}
... on PrismicPageDataBodyEmailSignup {
id
primary {
section_title {
richText
}
}
slice_type
}
... on PrismicPageDataBodyFullWidthImage {
id
primary {
image {
alt
url
}
}
slice_type
}
... on PrismicPageDataBodyHeadlineWithButton {
id
primary {
description {
richText
}
}
slice_type
}
... on PrismicPageDataBodyInfoWithImage {
id
primary {
text {
richText
}
}
slice_label
}
... on PrismicPageDataBodyTextInfo {
id
primary {
section_title {
richText
}
}
slice_type
}
}
}
}
}
When you add a fragment to a component and then import that component to a page, Gatsby automatically knows that the fragment can be used in a page query. Learn more about fragments in the Gatsby docs.
Arguments are parameters that you can add to filter the GraphQL response. They can be either static or dynamic. If they're dynamic, you pass your values in the form of variables.
The most common arguments you will use are:
- regex: filter by specific terms
- filter: filter by a field
- sort: sort results
- limit: limit the number of results
- skip: skip over a number of results
Explore all the available filtering options in the GraphQL Playground, accessible at http://localhost:8000/___graphql, when running your project in development.
You can only use fields from the Static Zone as arguments
You can only use fields from your document's Static Zone as arguments. You can not use fields inside Slices as arguments.
You can use the regex argument to search for documents that contain a given term or terms written as a regular expression in a string. It searches the term(s) in fields that retrieve string values, such ad the following field types:
- Rich Text
- Title
- Key Text
- UID
- Select
Here is an example to get all the Page type documents that mention the term "Art" in a Rich Text field with the API ID of content.
query MyQuery {
allPrismicPage(filter: {data: {content: {text: {regex: "/Art/i"}}}}) {
nodes {
data {
content {
richText
}
}
}
}
}
Use the filter argument with metadata fields as values to filter out the response.
query MyQuery {
allPrismicPage(filter: {first_publication_date: {eq: "2021-11-15"}}) {
nodes {
uid
}
}
}
Here are all the available metadata fields with usage examples:
id
filter: {id: {eq: "WsDFGHJt5df7"}}
uid
filter: {uid: {eq: "sample"}}
first_publication_date
filter: {first_publication_date: {eq: "2021-12-03"}}
last_publication_date
filter: {last_publication_date: {eq: "2019-12-03"}}
lang
filter: {lang: {eq: "en-us"}}
alternate_languages
filter: {alternate_languages: {lang: {eq: "en-us"}}}
tags
filter: {tags: {eq: "sports"}}
Use the filter argument with content fields as values to filter out the response
You can use Prismic fields at the top level of your documents to filter out the response. In the following example, we filter documents of the type 'Page' with a Boolean field with the API ID of example_boolean equal to true.
query MyPages {
allPrismicPage(filter: {data: {example_boolean: {eq: true}}}) {
nodes {
data {
example_boolean
}
}
}
}
Here are all the available content fields with usage examples.
Title
filter: {data: example_title: {text: {eq: "Today's news"}}}}
Rich Text
filter: {data: example_rich_text: {text: {eq: "innovation"}}}}
Image or Link to media
filter: {data: {example_image: {url: {eq: "https://images.prismic.io/repo/6e59446d"}}}}
Content Relationship
filter: {data: {example_content_relationsip: {id: {eq: "Wsdffgjoe3"}}}}
Link
filter: {data: {example_link: {url: {eq: "https://prismic.io/"}}}}
Date
filter: {data: {example_date: {eq: "2021-12-10"}}}
Timestamp
filter: {data: {example_timestamp: {eq: "2021-12-16T06:00:00+0000"}}}
Color
(filter: {data: {example_color: {eq: "#8a3535"}}})
Number
(filter: {data: {example_number: {eq: "100"}}})
Select or Key Text
filter: {data: {example_keytext: {eq: "placeholder"}}}
Boolean
filter: {data: {example_boolean: {eq: "true"}}}
Embed
filter: {data: {example_embed: {author_name: {eq: "Content creator"}}}}
Geopoint
filter: {data: {example_geopoint: {latitude: {eq: 0.076904}, longitude: {eq: 32.95571}}}}
Field in a Group
filter: {data: {example_group: {elemMatch: {example_boolean: {eq: true}}}}}
The sort argument helps you order your query results with two parameters:
- fields: specifies a Prismic metadata field or a content field API ID
- order: determines if you want the results to be sorted ascending (ASC) or descending (DESC)
In this example, the results of the documents are sorted in ascending order ASC by last_publication_date:
query MyPages {
allPrismicPage(sort: {fields: last_publication_date, order: ASC}) {
nodes {
uid
}
}
}
You can limit the number of documents retrieved in your response. In this example, we limit the response to three documents:
query MyPages {
allPrismicPage(limit: 3) {
nodes {
uid
}
}
}
You can skip over some results. In this example query, we skip the first three results of the documents:
query MyPages {
allPrismicPage(skip: 3) {
nodes {
uid
}
}
}
Content from Prismic comes in more than a dozen types. Most of these are simple primitive values, like Numbers or Booleans. Others are more complex structured values, like Titles, Rich Texts, and Links.
Prismic has 18 field types. Seven of those are simple fields that return a primitive value:
- Boolean
- Color
- Date
- Key Text
- Number
- Select
- Timestamp
Here's what retrieving any of these would look like:
query MyQuery {
prismicPage {
data {
example_number
}
}
}
The rest of the fields are objects with multiple properties that you can select. These fields are:
- Title and Rich Text
- Image
- Content Relationship
- Link
- Link to media
- Embed
- Geopoint
- Group
Let's take a look at examples of all the possible values you can retrieve from each of them:
- Title and Rich Text
- Image
- Content Relationship
- Link
- Link to media
- Embed
- Geopoint
- Group
query MyQuery {
prismicPage {
data {
example_title {
text
richText
html
}
}
}
}
query MyQuery {
prismicPost {
data {
example_image {
url
dimensions {
width
height
}
thumbnails {
desktop {
url
dimensions {
height
width
}
}
tablet {
url
dimensions {
height
width
}
}
}
}
}
}
}
query MyQuery {
prismicPost {
data {
example_content_relationship {
link_type
document {
... on PrismicExampleCustomType {
url
data {
example_title {
richText
}
}
}
}
}
}
}
}
query MyQuery {
prismicPost {
data {
example_external_link {
id
isBroken
lang
link_type
raw
size
slug
tags
target
type
uid
url
}
}
}
}
query MyQuery {
prismicPost {
data {
example_link_to_media {
id
isBroken
lang
link_type
raw
size
slug
tags
target
type
uid
url
document
}
}
}
}
query MyQuery {
prismicPost {
data {
example_embed {
author_name
author_url
embed_url
height
html
provider_name
provider_url
thumbnail_height
thumbnail_url
thumbnail_width
title
type
version
width
}
}
}
}
query MyQuery {
prismicPost {
data {
example_geopoint {
latitude
longitude
}
}
}
}
query MyQuery {
prismicPost {
data {
example_group {
example_number_in_list
}
}
}
}
Content Relationship fields use the union type to specify the content you need from a linked document.
In this example, we are telling the query to retrieve a document linked in the example_content_relationship field:
query MyQuery {
prismicPost {
data {
example_content_relationship {
link_type
document {
... on PrismicExampleCustomType {
url
data {
example_title {
richText
}
}
}
}
}
}
}
}
We use the union type inside queries to specify each of the Slices we need from a Custom Type using the following syntax:
... on PrismicExampleCustomTypeDataBodyExampleSlice
Where ExampleCustomType is the name of your Custom Type and ExampleSlice is the Slice's name.
In the following example, we have a Page Custom Type with one Slice called playlist with fields in both the repeatable (fields) and non-repeatable (primary) zones:
query MyQuery {
prismicPage {
data {
body {
... on PrismicPageDataBodyPlaylist {
slice_label
slice_type
primary {
playlist_name {
richText
}
}
fields {
song {
url
}
author {
richText
}
}
}
}
}
}
}
In singleton-type queries, the metadata fields are found in the first node of the query.
In repeatable type queries, the metadata fields are found inside edges > node.
Here's an example for a singleton query:
query MyQuery {
prismicPage {
uid
id
lang
type
last_publication_date
first_publication_date
alternate_languages {
lang
type
uid
id
}
}
}
Here's an example for repeatable documents:
query MyQuery {
allPrismicPost {
nodes {
uid
id
lang
type
last_publication_date
first_publication_date
alternate_languages {
lang
type
uid
id
}
}
}
}
After retrieving your Slices and fields, you're ready to template your content, preview your draft documents, and finally deploy your site. We'll detail how you can do that following pages.
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.