Our core development kits, @prismicio/client and @prismicio/helpers, have been refreshed with TypeScript support and more. Curious to try? Read more →

Arguments: filter, sort, limit & skip

In this article, you'll learn how to filter, sort, limit, and skip out the response in your Gatsby project.

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.

Operators

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:

Equal. Must match the given data exactly

In an array. Must be an element in the array

nin

Not in the array. Must not be an element in the array

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

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

Copy

query MyQuery {
  allPrismicPage(filter: {data: {content: {text: {regex: "/Art/i"}}}}) {
    nodes {
      data {
        content {
          richText
        }
      }
    }
  }
}

Filter

You can use the filter argument with content fields or metadata fields as values to filter out the response.

Using metadata

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

Copy

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

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

Using content fields

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 aren't available.

Copy

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

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

Sort: order your results

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: specifies 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 that are at the top level of your document will work as sort arguments. Fields inside Slices won't work.

Copy

query MyPages {
  allPrismicPage(sort: {fields: last_publication_date, order: ASC}) {
    nodes {
      uid
    }
  }
}

Limit

You can limit the number of documents retrieved in your response. In this example, we're limiting the response to three documents:

Copy

query MyPages {
  allPrismicPage(limit: 3) {
    nodes {
      uid
    }
  }
}

Skip

You can skip over some results. In this example query, we skip the first 3 results of the documents:

Copy

query MyPages {
  allPrismicPage(skip: 3) {
    nodes {
      uid
    }
  }
}

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.