Specify the new fetch documents route

open-api.yaml

@@ -1664,6 +1664,7 @@ paths:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/offset'
         - $ref: '#/components/parameters/fields'
+        - $ref: '#/components/parameters/filter'
     post:
       operationId: indexes.documents.create
       summary: Add or replace documents
@@ -1805,6 +1806,65 @@ paths:
           description: Not Found
     parameters:
       - $ref: '#/components/parameters/indexUid'
+  '/indexes/{indexUid}/documents/fetch':
+    post:
+      operationId: indexes.documents.fetch
+      summary: Get Documents
+      description: |
+        Get [documents](https://docs.meilisearch.com/learn/core_concepts/documents.html) by batch.
+      tags:
+        - Documents
+      security:
+        - apiKey: []
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/document'
+                  limit:
+                    $ref: '#/components/schemas/limit'
+                  offset:
+                    $ref: '#/components/schemas/offset'
+                  total:
+                    $ref: '#/components/schemas/total'
+                required:
+                  - results
+                  - limit
+                  - offset
+                  - total
+              examples:
+                Example:
+                  value:
+                    results:
+                      - id: 25684
+                        title: American Ninja 5
+                        poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
+                        overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
+                        release_date: 725846400
+                      - id: 45881
+                        title: The Bridge of San Luis Rey
+                        poster: 'https://image.tmdb.org/t/p/w500/4X7quIcdkc24Cveg5XdpfRqxtYA.jpg'
+                        overview: "The Bridge of San Luis Rey is American author Thornton Wilder's second novel, first published in 1927 to worldwide acclaim. It tells the story of several interrelated people who die in the collapse of an Inca rope-fiber suspension bridge in Peru, and the events that lead up to their being on the bridge.[ A friar who has witnessed the tragic accident then goes about inquiring into the lives of the victims, seeking some sort of cosmic answer to the question of why each had to die. The novel won the Pulitzer Prize in 1928."
+                        release_date: 1072915200
+                    limit: 20
+                    offset: 0
+                    total: 2
+        '401':
+          $ref: '#/components/responses/401'
+        '404':
+          description: Not Found
+      parameters:
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/offset'
+        - $ref: '#/components/parameters/fields'
+        - $ref: '#/components/parameters/filter'
   '/indexes/{indexUid}/documents/delete-batch':
     post:
       operationId: indexes.documents.removeBatch

text/0034-telemetry-policies.md

@@ -44,6 +44,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | Documents Added | Aggregated event on all received requests via the `POST` - `/indexes/:indexUid/documents` route during one hour or until a batch size reaches `500Kb`. |
 | Documents Updated | Aggregated event on all received requests via the `PUT` - `/indexes/:indexUid/documents` route during one hour or until a batch size reaches `500Kb`. |
 | Documents Deleted | Aggregated event on all received requests via the `DELETE` - `/indexes/:indexUid/documents`, `DELETE` - `/indexes/:indexUid/documents/:documentId`, `POST` - `indexes/:indexUid/documents/delete-batch` routes during one hour or until a batch size reaches `500Kb`.  |
+| Documents Fetched GET | Aggregated event on all received requests via the `GET` - `/indexes/:indexUid/documents` or `GET` - `/indexes/:indexUid/documents/:doc_id` routes during one hour or until a batch size reaches `500Kb`. |
+| Documents Fetched POST | Aggregated event on all received requests via the `POST` - `/indexes/:indexUid/documents/fetch` routes during one hour or until a batch size reaches `500Kb`.  |
 | Index Created | Occurs when an index is created via `POST` - `/indexes`. |
 | Index Updated | Occurs when an index is updated via `PUT` - `/indexes/:indexUid`. |
 | Indexes Swapped | Occurs when indexes are swapped via `POST` - `/swap-indexes`. |
@@ -112,15 +114,15 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | `requests.99th_response_time`           | Highest latency from among the fastest 99% of successful search requests | 57ms    | `Documents Searched POST`, `Documents Searched GET`|
 | `requests.total_succeeded`              | Total number of successful requests in this batch | 3456 | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` |
 | `requests.total_failed`                 | Total number of failed requests in this batch    | 24   | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` |
-| `requests.total_received`               | Total number of received requests in this batch  | 3480 | `Documents Searched POST`, `Documents Searched GET`, `Documents Deleted`, `Health Seen`, `Tasks Seen`, `Documents Searched by Multi-Search POST` |
+| `requests.total_received`               | Total number of received requests in this batch  | 3480 | `Documents Searched POST`, `Documents Searched GET`, `Documents Deleted`, `Documents Fetched GET`, `Documents Fetched POST`, `Health Seen`, `Tasks Seen`, `Documents Searched by Multi-Search POST` |
 | `sort.with_geoPoint`                    | `true` if the sort rule `_geoPoint` was used in this batch, otherwise `false` | true | `Documents Searched POST`, `Documents Searched GET` |
 | `sort.avg_criteria_number`              | Average number of sort criteria among all requests containing the `sort` parameter in this batch | 2 | `Documents Searched POST`, `Documents Searched GET` |
 | `filter.with_geoRadius`                 | `true` if the filter rule `_geoRadius` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` |
 | `filter.with_geoBoundingBox`            | `true` if the filter rule `_geoBoundingBox` was used in this batch, otherwise `false`| false | `Documents Searched POST`, `Documents Searched GET` |
 | `filter.most_used_syntax`               | Most used filter syntax among all requests containing the `filter` parameter in this batch | string | `Documents Searched POST`, `Documents Searched GET` |
 | `q.max_terms_number`                    | Highest number of terms given for the `q` parameter in this batch | 5 | `Documents Searched POST`, `Documents Searched GET` |
-| `pagination.max_limit`                  | Highest value given for the `limit` parameter in this batch | 60 | `Documents Searched POST`, `Documents Searched GET` |
-| `pagination.max_offset`                 | Highest value given for the `offset` parameter in this batch | 1000 | `Documents Searched POST`, `Documents Searched GET` |
+| `pagination.max_limit`                  | Highest value given for the `limit` parameter in this batch | 60 | `Documents Searched POST`, `Documents Searched GET`, `Documents Fetched GET`, `Documents Fetched POST` |
+| `pagination.max_offset`                 | Highest value given for the `offset` parameter in this batch | 1000 | `Documents Searched POST`, `Documents Searched GET`, `Documents Fetched GET`, `Documents Fetched POST` |
 | `pagination.most_used_navigation`       | Most used search results navigation among all search requests in this batch. `estimated` / `exhaustive` | `estimated` | `Documents Searched POST`, `Documents Searched GET` |
 | `formatting.max_attributes_to_retrieve` | The maximum number of attributes to retrieve encountered among all requests in this batch. | 100 | `Documents Searched POST`, `Documents Searched GET` |
 | `formatting.max_attributes_to_highlight` | The maximum number of attributes to highlight encountered among all requests in this batch. | 100 | `Documents Searched POST`, `Documents Searched GET` |
@@ -179,7 +181,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
 | indexes.total_single_index | The total number of calls where only one index where queried. | `2007` | `Documents Searched by Multi-Search POST`
 | `swap_operation_number`            | The number of swap operation given in `POST /swap-indexes` API call | 2 | `Indexes Swapped` |
 | `matching_strategy.most_used_strategy`      | Most used word matching strategy among all search requests in this batch | `last` | `Documents Searched POST`, `Documents Searched GET` |
-| `per_document_id` | `true` if `DELETE /indexes/:indexUid/documents/:documentUid` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` |
+| `per_document_id` | `true` if `DELETE /indexes/:indexUid/documents/:documentUid` or `GET /indexes/:indexUid/documents/:doc_id` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted`, `Documents Fetched GET` |
+| `per_filter` | `true` if `POST /indexes/:indexUid/documents/fetch` or `GET /indexes/:indexUid/documents/` endpoint was used with a filter in this batch, otherwise `false` | false | `Documents Fetched POST`, `Documents Fetched GET` |
 | `clear_all` | `true` if `DELETE /indexes/:indexUid/documents` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` |
 | `per_batch` | `true` if `POST /indexes/:indexUid/documents/delete-batch` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` |
 
@@ -395,6 +398,30 @@ This property allows us to gather essential information to better understand on
 | clear_all | `true` if `DELETE /indexes/:indexUid/documents` endpoint is called in the aggregated event, otherwise `false` | `false` |
 | per_batch | `true` if `POST /indexes/:indexUid/documents/delete-batch` endpoint is called in the aggregated event, otherwise `false` | `false` |
 
+## `Documents Fetched GET`
+
+> The Documents Fetched GET event is sent once an hour or when a batch reaches the maximum size of `500kb`.
+
+| Property name | Description | Example |
+|---------------|-------------|---------|
+| `requests.total_received` | Total number of request received in this batch | 325 |
+| `per_document_id` | `true` if `GET /indexes/:indexUid/documents/:doc_id` endpoint was used in this batch, otherwise `false` | false |
+| `per_filter` | `true` if `GET /indexes/:indexUid/documents` endpoint was used with a filter in this batch, otherwise `false` | false |
+| `pagination.max_limit` | Highest value given for the `limit` parameter in this batch | 60 |
+| `pagination.max_offset` | Highest value given for the `offset` parameter in this batch | 1000 |
+
+## `Documents Fetched POST`
+
+> The Documents Fetched POST event is sent once an hour or when a batch reaches the maximum size of `500kb`.
+
+| Property name | Description | Example |
+|---------------|-------------|---------|
+| `requests.total_received` | Total number of request received in this batch | 325 |
+| `per_document_id` | `false` | false |
+| `per_filter` | `true` if `POST /indexes/:indexUid/documents/fetch` endpoint was used with a filter in this batch, otherwise `false` | false |
+| `pagination.max_limit` | Highest value given for the `limit` parameter in this batch | 60 |
+| `pagination.max_offset` | Highest value given for the `offset` parameter in this batch | 1000 |
+
 ## `Settings Updated`
 
 | Property name | Description | Example |

text/0061-error-format-and-definitions.md

@@ -878,6 +878,29 @@ HTTP Code: `400 Bad Request`
 
 ---
 
+## invalid_document_filter
+
+`Synchronous`
+
+### Context
+
+This error occurs if a value with a different type than `String`, `Array of String` or `Array of array of String` for `filter` is specified.
+
+### Error Definition
+
+HTTP Code: `400 Bad Request`
+
+```json
+{
+    "message": "`:deserr_helper`",
+    "code": "invalid_document_filter",
+    "type": "invalid_request",
+    "link": "https://docs.meilisearch.com/errors#invalid_document_filter"
+}
+```
+
+---
+
 ## invalid_document_limit
 
 `Synchronous`

text/0085-api-keys.md

@@ -315,7 +315,7 @@ Create an API key.
 |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | search           | Provides access to `GET` and `POST` methods on `/indexes/:authorizedIndexes/search` routes.                                                                                                                                     |
 | documents.add    | Provides access to `POST` and `PUT` on `/indexes/:authorizedIndexes/documents` routes.                                                                                                                                          |
-| documents.get    | Provides access to `GET` methods on `/indexes/:authorizedIndexes/documents` and `/indexes/:authorizedIndexes/documents/:documentId` routes.                                                                                     |
+| documents.get    | Provides access to `GET` methods on `/indexes/:authorizedIndexes/documents`, `/indexes/:authorizedIndexes/documents/:documentId` and `POST` methods on `/indexes/:authorizedIndexes/documents/featch` routes.                                                                                     |
 | documents.delete | Provides access to `DELETE` method on `/indexes/:authorizedIndexes/documents/:documentId`, `indexes/:authorizedIndexes/documents/:documentId` and `POST` method on `/indexes/:authorizedIndexes/documents/delete-batch` routes. |
 | indexes.create   | Provides access to `POST` `/indexes`. **⚠️ `indexes` field should indicate the newly created index or having `[*]` to permits access on it.**.                                                                                   |
 | indexes.get      | Provides access to `GET` `/indexes` and `/indexes/:authorizedIndexes`. **⚠️Non-authorized `indexes` are omitted from the response on `/indexes`**.                                                                               |

text/0124-documents-api.md

@@ -20,21 +20,25 @@ Documents are stored inside indexes.
 
 Manipulate documents of a Meilisearch index.
 
-- [3.1.1. `GET` - `indexes/:index_uid/documents`](#311-get---indexesindexuiddocuments)
+- [3.1.1. (Fetch Documents) - `GET` - `indexes/:index_uid/documents` and `POST` - `indexes/:index_uid/documents/fetch](#311-fetch-documents-get-indexesindexuiddocuments-and-post-indexesindexuiddocumentsfetch)
 - [3.1.2. `GET` - `indexes/:index_uid/documents/:document_id`](#312-get---indexesindexuiddocumentsdocumentid)
 - [3.1.3. `POST` - `indexes/:index_uid/documents`](#313-post---indexesindexuiddocuments)
 - [3.1.4. `PUT` - `indexes/:index_uid/documents`](#314-put---indexesindexuiddocuments)
 - [3.1.5. `DELETE` - `indexes/:index_uid/documents`](#315-delete---indexesindexuiddocuments)
 - [3.1.6. `DELETE` - `indexes/:index_uid/documents/:document_id`](#316-delete---indexesindexuiddocumentsdocumentid)
 - [3.1.7. `POST` - `indexes/:index_uid/documents/delete-batch`](#317-post---indexesindexuiddocumentsdelete-batch)
 
-#### 3.1.1. `GET` - `indexes/:index_uid/documents`
+#### 3.1.1. (Fetch Documents) - `GET` - `indexes/:index_uid/documents` and `POST` - `indexes/:index_uid/documents/fetch
+
+Meilisearch exposes 2 routes to get the documents:
+- GET `indexes/:index_uid/documents`, which gets its parameters as query parameters.
+- POST `indexes/:index_uid/documents/fetch`, which gets its parameters in a json payload.
 
 List all documents of a Meilisearch index.
 
 The query parameters `offset` and `limit` permit browsing through all documents of an index.
 
-Meilisearch orders documents depending on the hash of their id.
+Meilisearch orders documents depending on the order they were inserted in the db.
 
 ##### 3.1.1.1. Path Parameters
 
@@ -49,13 +53,20 @@ Meilisearch orders documents depending on the hash of their id.
 
 Unique identifier of an index.
 
-##### 3.1.1.2. Query Parameters
+##### 3.1.1.2. Parameters
 
-| Field                    | Type                     | Required |
-|--------------------------|--------------------------|----------|
-| `offset`                 | Integer / `null`         | false    |
-| `limit`                  | String / `null`          | false    |
-| `fields`                 | String / `null`          | false    |
+The following parameters need to be send as:
+- Query parameter for the `GET` - `indexes/:index_uid/documents` route.
+- Json body for the `POST `indexes/:index_uid/documents/fetch` route.
+
+| Field                    | Type                      | Required |
+|--------------------------|---------------------------|----------|
+| `offset`                 | Integer                   | false    |
+| `limit`                  | Integer                   | false    |
+| `fields`                 | Array of Strings / `null` | false    |
+| `filter`                 | filter / `null`           | false    |
+
+In the case of the query parameter, as always, the `filter` can only be a string, while it can be either a string, an array of strings, or an array of array of strings for the json body.
 
 ###### 3.1.1.2.1. `offset`
 
@@ -75,7 +86,7 @@ Sets the maximum number of documents to be returned by the current request.
 
 ###### 3.1.1.2.3. `fields`
 
-- Type: String
+- Type: Array of Strings
 - Required: False
 - Default: `*`
 
@@ -92,6 +103,17 @@ If `fields` is not specified, all attributes from the documents are returned in
 
 > The index setting `displayedAttributes` has no impact on this endpoint.
 
+###### 3.1.1.2.4. `filter`
+
+- Type: String | Array of array of Strings
+- Required: False
+- Default: null
+
+Refine the results by selecting documents that match the given filter.
+In the case of the POST route, it is possible to send the filter in the form of an array of array of strings akin to the search route.
+
+Attributes used as filter criteria must be added to the `filterableAttributes` list of an index settings. See [Filterable Attributes Setting API](0123-filterable-attributes-setting-api.md).
+
 ##### 3.1.1.3. Response Definition
 
 A `results` array representing documents as JSON objects.
@@ -161,6 +183,7 @@ Gives the total number of documents that can be browsed in the related index.
 - 🔴 Sending a value with a different type than `Integer` or `null` for `offset` will return a [invalid_document_offset](0061-error-format-and-definitions.md#invalid_document_offset) error.
 - 🔴 Sending a value with a different type than `Integer` or `null` for `limit` will return a [invalid_document_limit](0061-error-format-and-definitions.md#invalid_document_limit) error.
 - 🔴 Sending a value with a different type than `String` or `null` for `fields` will return a [invalid_document_fields](0061-error-format-and-definitions.md#invalid_document_fields) error.
+- 🔴 Sending a value with a different type than `String`, `Array of strings`, `Array of array of strings` or `null` for `filter` will return a [invalid_document_filter](0061-error-format-and-definitions.md#invalid_document_filter) error.
 
 #### 3.1.2. `GET` - `indexes/:index_uid/documents/:document_id`
 
@@ -252,7 +275,7 @@ This endpoint accepts various content-type:
 
 - [`application/json`](0135-indexing-json.md)
 - [`text/csv`](0028-indexing-csv.md)
-- [`application/x-ndjson`](0028-indexing-ndjson.md)
+- [`application/x-ndjson`](0029-indexing-ndjson.md)
 
 ##### 3.1.3.1. Path Parameters
 
@@ -326,7 +349,7 @@ This endpoint accepts various content-type:
 
 - [`application/json`](0135-indexing-json.md)
 - [`text/csv`](0028-indexing-csv.md)
-- [`application/x-ndjson`](0028-indexing-ndjson.md)
+- [`application/x-ndjson`](0029-indexing-ndjson.md)
 
 ##### 3.1.4.1. Path Parameters