Arguments: Filter, Sort, Limit, and Skip
In this article, you'll learn how to filter, sort, limit, and skip out the response in your Gatsby project.
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.
Arguments work with operators. When making test queries in the Gatsby Playground, accessible at http://localhost:8000/___graphql when running your project in development, you'll notice that the filter argument allows you to select multiple types of operators. You'll only really need the ones we will list below:
eq
Equal. Must match the given data exactly
in
In an array. Must be an element in the array
nin
Not in the array. Must not be an element in the array
lt
Less than. Must be less than a given value
lte
Less than or equal. Must be less than or equal to the given value
regex
Short for regular expression, must match the given pattern
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
}
}
}
}
}
You can use the filter argument with content fields or metadata fields as values to filter out the response.
In the next example query, we filter documents of the type 'Page' where the metadata value first_publication_date is equal to "2021-11-15".
query MyQuery {
allPrismicPage(filter: {first_publication_date: {eq: "2021-11-15"}}) {
nodes {
uid
}
}
}
Here are all the available metadata fields with usage examples:
Example values
Note: we're using example metadata values. You'll need to replace these when making your own queries.
Metadata field
Example of usage
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"}}
You can use Prismic fields at the top level of your documents to filter out the response. In the next example, we filter documents of the type 'Page' with a Boolean field with the API ID of example_boolean equal to true.
⚠️ Top-level fields only
Please note that only fields at the top level of your document will work as arguments. Fields inside Slices aren't available.
query MyPages {
allPrismicPage(filter: {data: {example_boolean: {eq: true}}}) {
nodes {
data {
example_boolean
}
}
}
}
Example API IDs and Values
Values: We're using example content for the fields.
API IDs: We're using the field's name as the API ID itself with example_ appended at the beginning; for example, a Boolean field will be called example_boolean, and so on.
You'll need to replace these when making your queries.
Field
Example of usage
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}}}}
Group (one field inside the group)
filter: {data: {example_group: {elemMatch: {example_boolean: {eq: true}}}}}
The sort argument helps you order your query results with two parameters:
- field: 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 first_publication_date:
⚠️ Top-level fields only
Please note that only fields at the top level of your document will work as sort arguments. Fields inside Slices won't work.
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're determining 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
}
}
}
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.