Filtering and sorting by date

In this guide, you will learn about Meilisearch’s approach to date and time values, how to prepare your dataset for indexing, and how to chronologically sort and filter search results.

​

Preparing your documents

To filter and sort search results chronologically, your documents must have at least one field containing a UNIX timestamp. You may also use a string with a date in a format that can be sorted lexicographically, such as "2025-01-13".

As an example, consider a database of video games. In this dataset, the release year is formatted as a timestamp:

[
  {
    "id": 0,
    "title": "Return of the Obra Dinn",
    "genre": "adventure",
    "release_timestamp": 1538949600
  },
  {
    "id": 1,
    "title": "The Excavation of Hob's Barrow",
    "genre": "adventure",
    "release_timestamp": 1664316000
  },
  {
    "id": 2,
    "title": "Bayonetta 2",
    "genre": "action",
    "release_timestamp": 1411164000
  }
]

Once all documents in your dataset have a date field, index your data as usual. The example below adds a videogame dataset to a games index:

curl \
  -x POST 'MEILISEARCH_URL/indexes/games/documents' \
  -h 'content-type: application/json' \
  --data-binary @games.json

​

Filtering by date

To filter search results based on their timestamp, add your document’s timestamp field to the list of filterableAttributes:

curl \
  -X PUT 'MEILISEARCH_URL/indexes/games/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "release_timestamp"
  ]'

Once you have configured filterableAttributes, you can filter search results by date. The following query only returns games released between 2018 and 2022:

curl \
  -X POST 'MEILISEARCH_URL/indexes/games/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "",
    "filter": "release_timestamp >= 1514761200 AND release_timestamp < 1672527600"
  }'

​

Sorting by date

To sort search results chronologically, add your document’s timestamp field to the list of sortableAttributes:

curl \
  -X PUT 'MEILISEARCH_URL/indexes/games/settings/sortable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "release_timestamp"
  ]'

Once you have configured sortableAttributes, you can sort your search results based on their timestamp. The following query returns all games sorted from most recent to oldest:

curl \
  -X POST 'MEILISEARCH_URL/indexes/games/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "",
    "sort": ["release_timestamp:desc"]
  }'