From 1a3f49da5aec81d07749a237ad4d0ac02e9636df Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Mon, 31 Jul 2023 12:20:45 +0200 Subject: [PATCH] Vector Search - `EXPERIMENTAL` (#248) * Init spec * Fix the vector store fields * Add an information on the invalid_search_vector error code * Add an information on the invalid_vectors_field error codes * Define the new max_vector_size analytic * Update the open-api file with vector capabilities * Apply suggestions from code review * Update open-api.yaml Co-authored-by: Maria Craig * Update open-api.yaml Co-authored-by: Maria Craig * Update text/0118-search-api.md Co-authored-by: Maria Craig * Update text/0061-error-format-and-definitions.md Co-authored-by: Maria Craig --------- Co-authored-by: Kerollmops Co-authored-by: Maria Craig --- open-api.yaml | 9 ++ text/0034-telemetry-policies.md | 2 + text/0061-error-format-and-definitions.md | 57 ++++++++++ text/0118-search-api.md | 70 ++++++++---- text/0124-documents-api.md | 124 +++++++++++++--------- 5 files changed, 193 insertions(+), 69 deletions(-) diff --git a/open-api.yaml b/open-api.yaml index a80a78b5..c3c18e27 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -711,6 +711,11 @@ components: description: Query string. default: '""' example: '"Back to the future"' + vector: + type: array + description: Query vector. + default: 'null' + example: '[0.8, 0.145, 0.26, 0.3]' attributesToRetrieve: type: array description: 'Array of attributes whose fields will be present in the returned documents. Defaults to the [displayedAttributes list](https://docs.meilisearch.com/reference/features/settings.html#displayed-attributes) which contains by default all attributes found in the documents.' @@ -1754,6 +1759,8 @@ paths: > info > Use the reserved `_geo` object to add geo coordinates to a document. `_geo` is an object made of `lat` and `lng` field. + > + > Use the reserved `_vectors` arrays of floats to add embeddings to a document. `_vectors` is an array of floats or multiple arrays of floats in an outer array. tags: - Documents security: @@ -1808,6 +1815,8 @@ paths: > info > Use the reserved `_geo` object to add geo coordinates to a document. `_geo` is an object made of `lat` and `lng` field. + > + > Use the reserved `_vectors` arrays of floats to add embeddings to a document. `_vectors` is an array of floats or multiple arrays of floats in an outer array. tags: - Documents security: diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index 59ef4693..da1d9272 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -123,6 +123,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `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` | +| `vector.max_vector_size` | Highest number of dimensions given for the `vector` parameter in this batch | 1536 | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` | | `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` | @@ -273,6 +274,7 @@ This property allows us to gather essential information to better understand on | filter.avg_criteria_number | The average number of filter criteria among all the requests containing the `filter` parameter in the aggregated event. `"filter": []` equals to `0` while not sending `filter` does not influence the average in the aggregated event. | `4` | | filter.most_used_syntax | The most used filter syntax among all the requests containing the requests containing the `filter` parameter in the aggregated event. `string` / `array` / `mixed` | `mixed` | | q.max_terms_number | The maximum number of terms for the `q` parameter among all requests in the aggregated event. | `5` | +| vector.max_vector_size | The maximum number of dimensions for the `vector` parameter among all requests in the aggregated event. | `1536` | | pagination.max_limit | The maximum limit encountered among all requests in the aggregated event. | `20` | | pagination.max_offset | The maximum offset encountered among all requests in the aggregated event. | `1000` | | pagination.most_used_navigation | Most used search results navigation among all requests in the aggregated event. `estimated` / `exhaustive` | `estimated` || diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index d5d14bbb..c43f07e1 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -1474,6 +1474,31 @@ HTTP Code: `400 Bad Request` --- +## invalid_search_vector + +`Synchronous` + +### Context + +This error occurs for the listed reasons: +- if a value with a different type than `Array of Float` or `null` for `vector` is specified. +- if the vector length differs from the documents `_vectors` length. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "`:deserr_helper`", + "code": "invalid_search_vector", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_search_vector" +} +``` + +--- + ## invalid_search_offset `Synchronous` @@ -1937,6 +1962,38 @@ These errors occurs when the `_geo` field of a document payload is not valid. Ei --- +## invalid_document_vectors_field + +`Asynchronous` + +### Context + +This error occurs when the `_vectors` field of a document payload is not valid either due to the type of it or the number of dimensions. + +### Error Definition + +#### Variant: `_vectors` field value type is invalid + +```json +{ + "message": "The `_vectors` field in the document with the id: `:documentId` is not an array. Was expecting an array of floats or an array of arrays of floats but instead got `:field`", + "code": "invalid_document_vectors_type", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_document_vectors_type" +} +``` + +#### Variant: Number of dimensions is not correct + +```json +{ + "message": "Invalid vector dimensions: expected: `:expected`, found: `:found`.", + ... +} +``` + +--- + ## payload_too_large `Synchronous` diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 0b3ca2c5..ca20ed10 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -51,6 +51,7 @@ If a master key is used to secure a Meilisearch instance, the auth layer returns | [`cropMarker`](#3115-cropmarker) | String | False | | [`showMatchesPosition`](#3116-showmatchesposition) | Boolean | False | | [`matchingStrategy`](#3117-matchingStrategy) | String | False | +| [`vector`](#3118-vector) `EXPERIMENTAL` | Array of Float | False | #### 3.1.1. `q` @@ -912,22 +913,34 @@ The documents containing ALL the query words (i.e. in the `q` parameter) are ret Only the documents containing ALL the query words (i.e. in the `q` parameter) are returned by Meilisearch. If Meilisearch doesn't have enough documents to fit the requested `limit`, it returns the documents found without trying to match more documents. +#### 3.1.18. `vector` `EXPERIMENTAL` + +- Type: Array of Float +- Required: False +- Default: [] + +Request the nearest documents based on the query vector embedding given. + +- 🔴 Sending a value with a different type than `Array of Float` or `null` as a value for `vector` returns an [invalid_search_vector](0061-error-format-and-definitions.md#invalid_search_vector) error. +- 🔴 Sending a value for `vector` whose length differs from the documents `_vectors` length returns an [invalid_search_vector](0061-error-format-and-definitions.md#invalid_search_vector) error. + ### 3.2. Search Response Properties -| Field | Type | Required | -|-------------------------------------------------|------------|----------| -| [`hits`](#321-hits) | Array[Hit] | True | -| [`limit`](#322-limit) | Integer | False | -| [`offset`](#323-offset) | Integer | False | -| [`estimatedTotalHits`](#324-estimatedTotalHits) | Integer | False | -| [`page`](#325-page) | Integer | False | -| [`hitsPerPage`](#326-hitsperpage) | Integer | False | -| [`totalPages`](#327-totalpages) | Integer | False | -| [`totalHits`](#328-totalhits) | Integer | False | -| [`facetDistribution`](#329-facetdistribution) | Object | False | -| [`facetStats`](#3210-facetstats) | Object | False | -| [`processingTimeMs`](#3211-processingtimems) | Integer | True | -| [`query`](#3212-query) | String | True | +| Field | Type | Required | +|-------------------------------------------------|----------------|-----------| +| [`hits`](#321-hits) | Array[Hit] | True | +| [`limit`](#322-limit) | Integer | False | +| [`offset`](#323-offset) | Integer | False | +| [`estimatedTotalHits`](#324-estimatedTotalHits) | Integer | False | +| [`page`](#325-page) | Integer | False | +| [`hitsPerPage`](#326-hitsperpage) | Integer | False | +| [`totalPages`](#327-totalpages) | Integer | False | +| [`totalHits`](#328-totalhits) | Integer | False | +| [`facetDistribution`](#329-facetdistribution) | Object | False | +| [`facetStats`](#3210-facetstats) | Object | False | +| [`processingTimeMs`](#3211-processingtimems) | Integer | True | +| [`query`](#3212-query) | String | True | +| [`vector`](#3213-vector) `EXPERIMENTAL` | Array of Float | False | #### 3.2.1. `hits` @@ -944,11 +957,12 @@ A search result can contain special properties. See [3.2.1.1. `hit` Special Prop ##### 3.2.1.1. `hit` Special Properties -| Field | Type | Required | -|----------------------------------------------|---------|----------| -| [`_geoDistance`](#32111-geodistance) | Integer | False | -| [`_formatted`](#32112-formatted) | Object | False | -| [`_matchesPosition`](#32113-matchesposition) | Object | False | +| Field | Type | Required | +|-------------------------------------------------------------------|---------|----------| +| [`_geoDistance`](#32111-geodistance) | Integer | False | +| [`_formatted`](#32112-formatted) | Object | False | +| [`_matchesPosition`](#32113-matchesposition) | Object | False | +| [`_semanticScore`](#32114-semanticscore) `EXPERIMENTAL` | Float | False | ###### 3.2.1.1.1. `_geoDistance` @@ -1155,6 +1169,15 @@ The beginning of a matching term within a field is indicated by `start`, and its > See [3.1.14. `showMatchesPosition`](#3116-showmatchesposition) section. +###### 3.2.1.1.4. `_semanticScore` `EXPERIMENTAL` + +- Type: Float +- Required: False + +Contains the semantic similarity score of the document for a vector search when `vector` has been provided. The score is represented as a dot product. + +> See [3.1.18 `vector`](#3118-vector-experimental) + #### 3.2.2. `limit` - Type: Integer @@ -1271,6 +1294,15 @@ Query originating the response. Equals to the `q` search parameter. > See [3.1.1. `q`](#311-q) section. +#### 3.2.13. `vector` `EXPERIMENTAL` + +- Type: Array of Float +- Required: False + +Vector query embedding originating the response. Equals to the `vector` search parameter if specified. + +> See [3.1.18. `vector`](#3118-vector-experimental) + ## 2. Technical Details n/a diff --git a/text/0124-documents-api.md b/text/0124-documents-api.md index 6bab2579..1f9e70d6 100644 --- a/text/0124-documents-api.md +++ b/text/0124-documents-api.md @@ -261,7 +261,31 @@ A document represented as a JSON object. - 🔴 If the requested `document_id` does not exist, the API returns an [document_not_found](0061-error-format-and-definitions.md#document_not_found) 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. -#### 3.1.3. `POST` - `indexes/:index_uid/documents` +#### 3.1.3. Documents Body Special Properties + +While the body of a document can contain any pair of keys and values, Meilisearch uses specific key names to leverage some search capabilities such as geo search and vector search. + +| Field | Type | Required | +|----------------------------------------------------------|--------------------------|----------| +| [`_geo`](#3131-_geo) | String | Object | False | +| [`_vectors`](#3132-_vectors-experimental) `EXPERIMENTAL` | Array of Float | Array[Array of Float] | False | + +##### 3.1.3.1. `_geo` + +Holds latitude and longitude geo coordinates for a document. + +Refer to the [geo search specification](0059-geo-search.md) + +##### 3.1.3.2. `_vectors` `EXPERIMENTAL` + +Type: Array of Float | Array[Array of Float] +Required: False + +Holds a vectorized representation of a document. It is possible to send either one or several vectorized representations of the same document. + +- 🔴 Sending a value with a different type than `Array of Float`, `Array[Array of Float]` or `null` as a value for `_vectors` returns an [invalid_document_vectors_field](0061-error-format-and-definitions.md#invalid_document_vectors_field) error. +- 🔴 Sending a value for `_vectors` whose length differs from another document `_vectors` field returns an [invalid_document_vectors_field](0061-error-format-and-definitions.md#invalid_document_vectors_field) error. +#### 3.1.4. `POST` - `indexes/:index_uid/documents` Add a list of documents or replace them if they already exist. @@ -277,26 +301,26 @@ This endpoint accepts various content-type: - [`text/csv`](0028-indexing-csv.md) - [`application/x-ndjson`](0029-indexing-ndjson.md) -##### 3.1.3.1. Path Parameters +##### 3.1.4.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | True | -###### 3.1.3.1.1 `index_uid` +###### 3.1.4.1.1 `index_uid` - Type: String - Required: True Unique identifier of an index. -##### 3.1.3.2. Request Payload Definition +##### 3.1.4.2. Request Payload Definition | Field | Type | Required | |--------------------------|--------------------------|----------| | `primaryKey` | String | False | -###### 3.1.3.2.1 `primaryKey` +###### 3.1.4.2.1 `primaryKey` - Type: String - Required: False @@ -312,13 +336,13 @@ When the index is empty, it is possible to modify the `primaryKey`. If the index is not empty, the query parameter `primaryKey` is ignored. -##### 3.1.3.3. Response Definition +##### 3.1.4.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.3.4. Errors +##### 3.1.4.4. Errors - 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. - 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. @@ -328,16 +352,16 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. - 🔴 Sending a value with a different type than `String` or `null` for the `primaryKey` parameter will return a [invalid_index_primary_key](0061-error-format-and-definitions.md#invalid_index_primary_key) error. -###### 3.1.3.4.1. Async Errors +###### 3.1.4.4.1. Async Errors - 🔴 When Meilisearch is secured, if the API Key do not have the `indexes.create` action defined, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error in the related asynchronous `task` resource. See [3.2.2.2. Response Definition](#3222-response-definition). - 🔴 When updating the `primaryKey`, if the previous `primaryKey` value has already been used for a document, the API returns an [index_primary_key_already_exists](0061-error-format-and-definitions.md#index_primary_key_already_exists) error. -##### 3.1.3.5. Lazy Index Creation +##### 3.1.4.5. Lazy Index Creation If the requested `index_uid` does not exist, and the authorization layer allows it (See [3.1.3.4.1. Async Errors](#31341-async-errors)), Meilisearch will create the index when the related asynchronous task resource is executed. See [3.1.3.3. Response Definition](#3133-response-definition). -#### 3.1.4. `PUT` - `indexes/:index_uid/documents` +#### 3.1.5. `PUT` - `indexes/:index_uid/documents` Add a list of documents or update them if they already exist. @@ -351,26 +375,26 @@ This endpoint accepts various content-type: - [`text/csv`](0028-indexing-csv.md) - [`application/x-ndjson`](0029-indexing-ndjson.md) -##### 3.1.4.1. Path Parameters +##### 3.1.5.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | True | -###### 3.1.4.1.1. `index_uid` +###### 3.1.5.1.1. `index_uid` - Type: String - Required: True Unique identifier of an index. -##### 3.1.4.2. Query Parameters Definition +##### 3.1.5.2. Query Parameters Definition | Field | Type | Required | |--------------------------|--------------------------|----------| | `primaryKey` | String | False | -###### 3.1.4.2.1. `primaryKey` +###### 3.1.5.2.1. `primaryKey` - Type: String - Required: False @@ -386,13 +410,13 @@ When the index is empty, it is possible to modify the `primaryKey`. If the index is not empty, the query parameter `primaryKey` is ignored. -##### 3.1.4.3. Response Definition +##### 3.1.5.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.4.4. Errors +##### 3.1.5.4. Errors - 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. - 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. @@ -402,109 +426,109 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. - 🔴 Sending a value with a different type than `String` or `null` for the `primaryKey` parameter will return a [invalid_index_primary_key](0061-error-format-and-definitions.md#invalid_index_primary_key) error. -###### 3.1.4.4.1. Async Errors +###### 3.1.5.4.1. Async Errors - 🔴 When Meilisearch is secured, if the API Key do not have the `indexes.create` action defined, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error in the related asynchronous `task` resource. See [3.2.2.2. Response Definition](#3222-response-definition). - 🔴 When updating the `primaryKey`, if the previous `primaryKey` value has already been used for a document, the API returns an [index_primary_key_already_exists](0061-error-format-and-definitions.md#index_primary_key_already_exists) error. -##### 3.1.4.5. Lazy Index Creation +##### 3.1.5.5. Lazy Index Creation If the requested `index_uid` does not exist, and the authorization layer allows it (See [3.1.4.4.1. Async Errors](#31441-async-errors)), Meilisearch will create the index when the related asynchronous task resource is executed. See [3.1.4.3. Response Definition](#3143-response-definition). -#### 3.1.5. `DELETE` - `indexes/:index_uid/documents` +#### 3.1.6. `DELETE` - `indexes/:index_uid/documents` Delete all documents in the specified index. -##### 3.1.5.1. Path Parameters +##### 3.1.6.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | true | -###### 3.1.5.1.1. `index_uid` +###### 3.1.6.1.1. `index_uid` - Type: String - Required: True Unique identifier of an index. -##### 3.1.5.2. Request Payload Definition +##### 3.1.6.2. Request Payload Definition N/A -##### 3.1.5.3. Response Definition +##### 3.1.6.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.5.4. Errors +##### 3.1.6.4. Errors - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. -###### 3.1.5.4.1. Async Errors +###### 3.1.6.4.1. Async Errors - 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. -#### 3.1.6. `DELETE` - `indexes/:index_uid/documents/:document_id` +#### 3.1.7. `DELETE` - `indexes/:index_uid/documents/:document_id` Delete one document based on its unique id. -##### 3.1.6.1. Path Parameters +##### 3.1.7.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | True | | `document_id` | String | True | -###### 3.1.6.1.1. `index_uid` +###### 3.1.7.1.1. `index_uid` - Type: String - Required: True Unique identifier of an index. -###### 3.1.6.1.2. `document_id` +###### 3.1.7.1.2. `document_id` - Type: Integer - Required: True Unique identifier of a document. -##### 3.1.6.2. Request Payload Definition +##### 3.1.7.2. Request Payload Definition N/A -##### 3.1.6.3. Response Definition +##### 3.1.7.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.6.4. Errors +##### 3.1.7.4. Errors - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. -###### 3.1.6.4.1. Async Errors +###### 3.1.7.4.1. Async Errors - 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. -#### 3.1.7. `POST` - `indexes/:index_uid/documents/delete-batch` +#### 3.1.8. `POST` - `indexes/:index_uid/documents/delete-batch` Delete a selection of documents based on array of document id's. -##### 3.1.7.1. Path Parameters +##### 3.1.8.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | True | -###### 3.1.7.1.1. `index_uid` +###### 3.1.8.1.1. `index_uid` - Type: String - Required: True Unique identifier of an index. -##### 3.1.7.2 Request Payload Definition +##### 3.1.8.2 Request Payload Definition An array of document ids to delete. @@ -517,13 +541,13 @@ e.g. [122, 1194, 2501] ``` -##### 3.1.7.3. Response Definition +##### 3.1.8.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task with the type `documentDeletion`. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.7.4. Errors +##### 3.1.8.4. Errors - 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. - 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. @@ -533,28 +557,28 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t - 🔴 Sending an invalid index uid format for the `:index_uid` path parameter returns an [invalid_index_uid](0061-error-format-and-definitions.md#invalid_index_uid) error. - 🔴 Sending a value with a different type than `Array` for the body request will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -###### 3.1.7.4.1 Async Errors +###### 3.1.8.4.1 Async Errors - 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. -#### 3.1.8. `POST` - `indexes/:index_uid/documents/delete` +#### 3.1.9. `POST` - `indexes/:index_uid/documents/delete` Delete a selection of documents based on a filter. -##### 3.1.8.1. Path Parameters +##### 3.1.9.1. Path Parameters | Field | Type | Required | |--------------------------|--------------------------|----------| | `index_uid` | String | True | -###### 3.1.8.1.1. `index_uid` +###### 3.1.9.1.1. `index_uid` - Type: String - Required: True Unique identifier of an index. -##### 3.1.8.2 Request Payload Definition +##### 3.1.9.2 Request Payload Definition A filter. @@ -569,13 +593,13 @@ e.g. } ``` -##### 3.1.8.3. Response Definition +##### 3.1.9.3. Response Definition When the request is successful, Meilisearch returns the HTTP code `202 Accepted`. The response's content is the summarized representation of the received asynchronous task with the type `documentDeletion`. See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-task-object-for-202-accepted). -##### 3.1.8.4. Errors +##### 3.1.9.4. Errors - 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. - 🔴 Sending an empty Content-Type returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. @@ -586,15 +610,15 @@ See [Summarized `task` Object for `202 Accepted`](0060-tasks-api.md#summarized-t - 🔴 Sending a value without a filter will return a [missing_document_filter](0061-error-format-and-definitions.md#missing_document_filter) error. - 🔴 Sending a value with an invalid or empty filter will return an [invalid_document_filter](0061-error-format-and-definitions.md#invalid_document_filter) error. -###### 3.1.8.4.1 Async Errors +###### 3.1.9.4.1 Async Errors - 🔴 If the requested `index_uid` does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. -#### 3.1.9. General Errors +#### 3.1.10. General Errors These errors apply to all endpoints described here. -##### 3.1.9.1 Auth Errors +##### 3.1.10.1 Auth Errors The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). @@ -606,4 +630,4 @@ N/A ## 5. Future Possibilities -- Introduce a way to reject fields from a document in the response. e.g. `?fields=-createdAt` \ No newline at end of file +- Introduce a way to reject fields from a document in the response. e.g. `?fields=-createdAt`