Fetch Data

On this page, you'll learn how to retrieve content from your Prismic repository using the Gatsby source plugin.

Basic queries

You have two options to write your queries: one that returns a single document and another that returns all documents of a type. Which one you use depends on how you plan to use your content.

The following examples query for one or multiple documents for a Custom Type named 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.

Fragments

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, but the first example with fragments make the code shorter and more** **legible.

With fragments:

query pageQuery($id: String, $lang: String) {
	prismicPage(id: { eq: $id }, lang: { eq: $lang }) {
		data {
			body {
				... on PrismicSlice {
					id
					slice_label
					slice_type
				}
				...PageDataBodyEmailSignup
				...PageDataBodyFullWidthImage
				...PageDataBodyHeadlineWithButton
				...PageDataBodyInfoWithImage
				...PageDataBodyTextInfo
			}
		}
	}
}

Without fragments:

query pageQuery($id: String, $lang: String) {
	prismicPage(id: { eq: $id }, lang: { eq: $lang }) {
		data {
			body {
				... on PrismicSlice {
					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

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 GraphiQL 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.

Filter by search

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

Filter by metadata

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:

Property	Description
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"}}

Filter by a field

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.

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

Sort results

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

Limit results

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

Skip results

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

Selecting fields

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.

Fields

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:

query MyQuery {
	prismicPage {
		data {
			example_title {
				text
				richText
				html
			}
		}
	}
}

Image:

query MyQuery {
	prismicPost {
		data {
			example_image {
				url
				dimensions {
					width
					height
				}
				thumbnails {
					desktop {
						url
						dimensions {
							height
							width
						}
					}
					tablet {
						url
						dimensions {
							height
							width
						}
					}
				}
			}
		}
	}
}

Content Relationship:

query MyQuery {
	prismicPost {
		data {
			example_content_relationship {
				link_type
				document {
					... on PrismicExampleCustomType {
						url
						data {
							example_title {
								richText
							}
						}
					}
				}
			}
		}
	}
}

Link:

query MyQuery {
	prismicPost {
		data {
			example_external_link {
				id
				isBroken
				lang
				link_type
				raw
				size
				slug
				tags
				target
				type
				uid
				url
			}
		}
	}
}

Link to media:

query MyQuery {
	prismicPost {
		data {
			example_link_to_media {
				id
				isBroken
				lang
				link_type
				raw
				size
				slug
				tags
				target
				type
				uid
				url
				document
			}
		}
	}
}

Embed:

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

Geopoint:

query MyQuery {
	prismicPost {
		data {
			example_geopoint {
				latitude
				longitude
			}
		}
	}
}

Group:

query MyQuery {
	prismicPost {
		data {
			example_group {
				example_number_in_list
			}
		}
	}
}

Nested Content

Use the union type ... on syntax to query fields from Content relationship field's nested content.

In this example, we are querying a linked document in the example_content_relationship field:

query MyQuery {
	prismicPost {
		data {
			example_content_relationship {
				link_type
				document {
					... on PrismicExampleCustomType {
						url
						data {
							example_title {
								richText
							}
						}
					}
				}
			}
		}
	}
}

Slices

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 (items) and non-repeatable (primary) zones:

query MyQuery {
	prismicPage {
		data {
			body {
				... on PrismicPageDataBodyPlaylist {
					slice_label
					slice_type
					primary {
						playlist_name {
							richText
						}
					}
					items {
						song {
							url
						}
						author {
							richText
						}
					}
				}
			}
		}
	}
}

Metadata fields

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 > nodes.

Here's an example of 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
			}
		}
	}
}

Next steps

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.

Next article: Define Routes
Previous article: Set up Prismic

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

03-fetch-data.md

03-fetch-data.md

Fetch Data

Basic queries

Fragments

Arguments

Filter by search

Filter by metadata

Filter by a field

Sort results

Limit results

Skip results

Selecting fields

Fields

Nested Content

Slices

Metadata fields

Next steps

Files

03-fetch-data.md

Latest commit

History

03-fetch-data.md

File metadata and controls

Fetch Data

Basic queries

Fragments

Arguments

Filter by search

Filter by metadata

Filter by a field

Sort results

Limit results

Skip results

Selecting fields

Fields

Nested Content

Slices

Metadata fields

Next steps