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

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

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:

  • 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

Filter

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

Filter using metadata

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.

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

Filter using Prismic 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 won't work.

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

Filter using Prismic Group fields

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.

Copy
filter: {data: {example_group: {elemMatch: {example_boolean: {eq: false}}}}}

Sort: order your results

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.

Copy
query MyPages {
  allPrismicPage(sort: {fields: last_publication_date, order: ASC}) {
    edges {
      node {
        uid
      }
    }
  }
}

Limit

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

Copy
query MyPages {
  allPrismicPage(limit: 3) {
    edges {
      node {
        uid
      }
    }
  }
}

Skip

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

Copy
query MyPages {
  allPrismicPage(skip: 3) {
    edges {
      node {
        uid
      }
    }
  }
}