Arguments: filter, sort, limit & skip
In this article, you'll learn about all the possible options you have when using Gatsby's arguments to filter, sort, limit, and skip out the response.
Arguments serve as parameters that you can add to filter the response. These parameters are always located at the root level field of your queries, and they can be either static or dynamic. If they're dynamic, you should pass your values in the form of variables.
We will go over the 4 top-level argument options that you can use for your document queries. Each one has its own section in this same document further below.
- filter: Used to show only results that match the values passed to the operators
- sort: Order the results to be ascending or descending
- limit: To reduce the number of results from a query
- skip: Skip over certain results
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: Short for equal, must match the given data exactly
- in: Short for in an array, must be an element in the array
- nin: Short for not in the array, must NOT be an element in the array
- lt: Short for less than, must be less than a given value
- lte: Short for less than or equal, must be less than or equal to the given value
You can use the filter argument to filter out the response with Custom Type fields or metadata fields as values.
You can use the metadata fields of your documents to filter out the response. In the next example, we filter documents of the type 'Page' with the first_publication_date equal to 2020-04-15.
query MyPages {
allPrismicPage(filter: {first_publication_date: {eq: "2020-04-15"}}) {
edges {
node {
uid
}
}
}
}All the available options:
id
filter: {id: {eq: "WsDFGHJt5df7"}}uid
filter: {uid: {eq: "sample"}}first_publication_date
filter: {first_publication_date: {eq: "2020-12-03"}}last_publication_date
filter: {last_publication_date: {eq: "2019-12-03"}}lang
filter: {lang: {eq: "en-us"}}alternate_languages
filter: {alternate_languages: {elemMatch: {lang: {eq: "en-us"}}}}tags
filter: {tags: {eq: "sports"}}⚠️ Example values
Note: we're using example values. You'll need to replace these when making your own queries.
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 that are at the top level of your document will work as arguments. Fields inside Slices won't work.
query MyPages {
allPrismicPage(filter: {data: {example_boolean: {eq: true}}}) {
edges {
node {
example_boolean
}
}
}
}Example API IDs and Values
Values: We are using sample values and API ID to showcase the examples.
API IDs: We're using the name of the field 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 own queries.
All the available options:
Title
filter: {data: {example_title: {elemMatch: {text: {eq: "Today's news"}}}}}Rich Text
filter: {data: {example_rich_text: {elemMatch: {text: {eq: "innovation"}}}}}Image / 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: "2020-12-10"}}}Timestamp
filter: {data: {example_timestamp: {eq: "2020-12-16T06:00:00+0000"}}}Color
(filter: {data: {example_color: {eq: "#8a3535"}}})Number
(filter: {data: {example_number: {eq: "100"}}})Select / 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: false}}}}}You can use Prismic Groups 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, inside of a Group field with the API ID of example_group.
filter: {data: {example_group: {elemMatch: {example_boolean: {eq: false}}}}}The ordering of your results can be specified with sort. You use two parameters for this argument: field to specify the Prismic field ID and order to specify if you want it sorted ascending (ASC) or descending (DESC). You can use any metadata or Prismic field.
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 that are 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}) {
edges {
node {
uid
}
}
}
}You can limit the number of documents retrieved in your response. In this example, we're limiting the response to three 'Page' documents:
query MyPages {
allPrismicPage(limit: 3) {
edges {
node {
uid
}
}
}
}You can skip over some results. In this example query, we skip the first 3 results of the 'Page' documents:
query MyPages {
allPrismicPage(skip: 3) {
edges {
node {
uid
}
}
}
}