diff --git a/open-api.yaml b/open-api.yaml index be6735af..37cd6ee3 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -405,6 +405,42 @@ components: - exactness - 'release_date:asc' examples: [] + typoTolerance: + type: object + description: Customize typo tolerance feature. + properties: + enabled: + description: Enable the typo tolerance feature. + type: boolean + default: true + nullable: false + disableOnAttributes: + description: Disable the typo tolerance feature on the specified attributes. + type: array + items: + type: string + default: [] + nullable: false + disableOnWords: + description: Disable the typo tolerance feature for a set of query terms given for a search query. + type: array + items: + type: string + default: [] + nullable: false + minWordSizeForTypos: + type: object + properties: + oneTypo: + description: Customize the minimum size for a word to tolerate 1 typo. + type: integer + default: 5 + nullable: false + twoTypos: + description: Customize the minimum size for a word to tolerate 2 typos. + type: integer + default: 9 + nullable: false filterableAttributes: type: array description: | @@ -458,6 +494,8 @@ components: $ref: '#/components/schemas/searchableAttributes' displayedAttributes: $ref: '#/components/schemas/displayedAttributes' + typoTolerance: + $ref: '#/components/schemas/typoTolerance' required: - synonyms - stopWords @@ -466,6 +504,7 @@ components: - distinctAttribute - searchableAttributes - displayedAttributes + - typoTolerance stats: type: object additionalProperties: false @@ -1607,6 +1646,8 @@ paths: $ref: '#/components/schemas/filterableAttributes' sortableAttributes: $ref: '#/components/schemas/sortableAttributes' + typoTolerance: + $ref: '#/components/schemas/typoTolerance' required: - rankingRules - distinctAttribute @@ -1616,6 +1657,7 @@ paths: - synonyms - filterableAttributes - sortableAttributes + - typoTolerance examples: Example: value: @@ -1657,6 +1699,16 @@ paths: - price - author - title + typoTolerance: + enabled: true + disableOnAttributes: + - author + - price + disableOnWords: + - Tolkien + minWordSizeForTypos: + oneTypo: 4 + twoTypos: 8 '401': $ref: '#/components/responses/401' '404': @@ -1700,6 +1752,8 @@ paths: $ref: '#/components/schemas/filterableAttributes' sortableAttributes: $ref: '#/components/schemas/sortableAttributes' + typoTolerance: + $ref: '#/components/schemas/typoTolerance' examples: Example: value: @@ -1736,6 +1790,16 @@ paths: - release_date filterableAttributes: [] sortableAttributes: null + typoTolerance: + enabled: false + disableOnAttributes: + - title + - author + disableOnWords: + - Tolkien + minWordSizeForTypos: + oneTypo: 4 + twoTypos: 8 responses: '202': $ref: '#/components/responses/202' @@ -2054,6 +2118,74 @@ paths: description: Not Found parameters: - $ref: '#/components/parameters/indexUid' + '/indexes/{indexUid}/settings/typo-tolerance': + get: + operationId: indexes.settings.typoTolerance.get + summary: Get typo tolerance configuration + description: | + Get the typo tolerance configuration of an index. + tags: + - Settings + security: + - apiKey: [] + responses: + '200': + description: Ok + content: + application/json: + schema: + $ref: '#/components/schemas/typoTolerance' + '401': + $ref: '#/components/responses/401' + '404': + description: Not Found + post: + operationId: indexes.settings.typoTolerance.update + summary: Update typo tolerance settings + description: | + Update the typo tolerance configuration of an index. + + > info + > If the provided index does not exist, it will be created. + tags: + - Settings + security: + - apiKey: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/typoTolerance' + examples: {} + description: '' + responses: + '202': + $ref: '#/components/responses/202' + '401': + $ref: '#/components/responses/401' + '404': + description: Not Found + parameters: + - $ref: '#/components/parameters/Content-Type' + delete: + operationId: indexes.settings.typoTolerance.reset + summary: Reset typo tolerance settings to the default configuration + description: | + Reset the typo tolerance settings of an index to its default configuration. + tags: + - Settings + security: + - apiKey: [] + responses: + '202': + $ref: '#/components/responses/202' + '401': + $ref: '#/components/responses/401' + '404': + description: Not Found + parameters: + - $ref: '#/components/parameters/indexUid' '/indexes/{indexUid}/settings/filterable-attributes': get: operationId: indexes.settings.filterableAttributes.get diff --git a/text/0034-telemetry-policies.md b/text/0034-telemetry-policies.md index b9dba20f..d628a7ab 100644 --- a/text/0034-telemetry-policies.md +++ b/text/0034-telemetry-policies.md @@ -54,6 +54,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | RankingRules Updated | Occurs when ranking rules are updated via `POST` - `/indexes/:indexUid/settings/ranking-rules`. | | FilterableAttributes Updated | Occurs when filterable attributes are updated via `POST` - `/indexes/:indexUid/settings/filterable-attributes`. | | SortableAttributes Updated | Occurs when sortable attributes are updated via `POST` - `/indexes/:indexUid/settings/sortable-attributes`. | +| TypoTolerance Updated | Occurs when typo tolerance settings are updated via `POST` - `/indexes/:indexUid/settings/typo-tolerance`. | | Dump Created | Occurs when a dump is created via `POST` - `/dumps`. | | Tasks Seen | Occurs when tasks are fetched globally via `GET` - `/tasks`. | | Index Tasks Seen | Occurs when tasks are filtered by index via `GET` - `/indexes/:indexUid/tasks`. | @@ -116,7 +117,12 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat | `sortable_attributes.has_geo` | `true` if `_geo` is set as a sortable attribute, otherwise `false` | true | `Settings Updated`, `SortableAttributes Updated` | | `filterable_attributes.total` | Number of filterable attributes | 3 | `Settings Updated`, `FilterableAttributes Updated` | | `filterable_attributes.has_geo` | `true` if `_geo` is set as a filterable attribute, otherwise `false` | false | `Settings Updated`, `FilterableAttributes Updated`| -| `searchable_attributes.total` | Number of searchable attributes | 4 | `Settings Updated`, `SearchableAttributes Update` | +| `searchable_attributes.total` | Number of searchable attributes | 4 | `Settings Updated`, `SearchableAttributes Updated` | +| `typo_tolerance.enabled` | Whether the typo tolerance is enabled | `true` | `Settings Updated`, `TypoTolerance Updated` | +| `typo_tolerance.disable_on_attributes` | `true` if at least one value is defined | `false` | `Settings Updated`, `TypoTolerance Updated` | +| `typo_tolerance.disable_on_words` | `true` if at least one value is defined | `false` | `Settings Updated`, `TypoTolerance Updated` | +| `typo_tolerance.min_word_size_for_typos.one_typo` | The defined value for `minWordSizeForTypos.oneTypo` property | `5` | `Settings Updated`, `TypoTolerance Updated` | +| `typo_tolerance.min_word_size_for_typos.two_typos`| The defined value for `minWordSizeForTypos.twoTypos` property | `9` | `Settings Updated`, `TypoTolerance Updated` | | `per_task_uid` | `true` if an uid is used to fetch a particular task resource, otherwise `false` | true | `Tasks Seen`, `Index Tasks Seen` | | @@ -275,12 +281,18 @@ This property allows us to gather essential information to better understand on | Property name | Description | Example | |---------------|-------------|---------| | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | +| searchable_attributes.total | Number of searchable attributes. | `3`| | ranking_rules.sort_position | Position of the `sort` ranking rule if any, otherwise `null`. | `5` | | sortable_attributes.total | Number of sortable attributes. | `3` | | sortable_attributes.has_geo | Indicate if `_geo` is set as a sortable attribute. | `false`| | filterable_attributes.total | Number of filterable attributes. | `3` | | filterable_attributes.has_geo | Indicate if `_geo` is set as a filterable attribute. | `false`| -| searchable_attributes.total | Number of searchable attributes. | `3`| +| typo_tolerance.enabled | Whether the typo tolerance is enabled. | `true` | +| typo_tolerance.disable_on_attributes | `true` if at least one value is defined for `disableOnAttributes` property. | `false` | +| typo_tolerance.disable_on_words | `true` if at least one value is defined for `disableOnWords` property. | `false` | +| typo_tolerance.min_word_size_for_typos.one_typo | The defined value for `minWordSizeForTypos.oneTypo` property. | `5` | +| typo_tolerance.min_word_size_for_typos.two_typos | The defined value for `minWordSizeForTypos.twoTypos` property. | `9` | + --- ## `RankingRules Updated` @@ -317,6 +329,17 @@ This property allows us to gather essential information to better understand on | user_agent | Represents the user-agent encountered on this call. | `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` | | searchable_attributes.total | Number of searchable attributes. | `3` | + +## `TypoTolerance Updated` + +| Property name | Description | Example | +|---------------|-------------|---------| +| typo_tolerance.enabled | Whether the typo tolerance is enable.d | `true` | +| typo_tolerance.disable_on_attributes | `true` if at least one value is defined for `disableOnAttributes` property. | `false` | +| typo_tolerance.disable_on_words | `true` if at least one value is defined for `disableOnWords` property. | `false` | +| typo_tolerance.min_word_size_for_typos.one_typo | The defined value for `minWordSizeForTypos.oneTypo` property. | `5` | +| typo_tolerance.min_word_size_for_typos.two_typos | The defined value for `minWordSizeForTypos.twoTypos` property. | `9` | + ## `Dump Created` | Property name | Description | Example | diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md index 4b9f48ef..e2130a50 100644 --- a/text/0061-error-format-and-definitions.md +++ b/text/0061-error-format-and-definitions.md @@ -222,6 +222,30 @@ HTTP Code: `400 Bad Request` --- +## invalid_typo_tolerance_min_word_size_for_typos + +`Asynchronous` + +### Context + +This error happens when the `minWordSizeForTypos` object of the `typo` resource is invalid. + +### Error Definition + +```json +{ + "message": "`minWordSizeForTypos` setting is invalid. `oneTypo` and `twoTypos` fields should be between `0` and `255`, and `twoTypos` should be greater or equals to `oneTypo` but found `oneTypo: :oneTypo` and twoTypos: twoTypos`.", + "code": "invalid_typo_tolerance_min_word_size_for_typos", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_typo_tolerance_min_word_size_for_typos" +} +``` + +- The `:oneTypo` is inferred when the message is generated. +- The `:twoTypos` is inferred when the message is generated. + +--- + ## index_already_exists `Asynchronous` diff --git a/text/0117-typo-tolerance-setting-api.md b/text/0117-typo-tolerance-setting-api.md new file mode 100644 index 00000000..45161729 --- /dev/null +++ b/text/0117-typo-tolerance-setting-api.md @@ -0,0 +1,296 @@ +# Typo Tolerance Settings API + +## 1. Summary + +This specification describes the customizable options for the typo tolerance settings. + +## 2. Motivation + +Tolerance to typos is critical when building an enjoyable search experience. Meilisearch ranks typo-free matched documents above others based on the default settings that we believe are best for most users. + +Meilisearch can adapt to different use-cases by providing customization options for the typo tolerance feature. + +## 3. Functional Specification + +### 3.1. `typoTolerance` API resource definition + +| Field | Type | Required | +|--------------------------------------------------|-----------------|----------| +| [enabled](#311-enabled) | Boolean | False | +| [disableOnAttributes](#312-disableOnattributes) | Array of String | False | +| [disableOnWords](#313-disableOnwords) | Array of String | False | +| [minWordSizeForTypos](#314-minwordsizefortypos) | Object | False | + +#### 3.1.1. `enabled` + +- Type: Boolean +- Required: False +- Default: `true` + +Whether the typo tolerance feature is enabled. + +##### 3.1.1.1. Impacts on the `typo` ranking rule + +The presence of `typo` in the ranking rules setting does not influence the activation/deactivation of the typo tolerance feature. + +If the `rankingRules` parameter of the index settings does not contain the `typo` rule, the results are not sorted according to the number of typos found. + +The typo tolerance feature is still used to match documents. + +### 3.1.2. `disableOnAttributes` + +- Type: Array of String +- Required: False +- Default: `[]` + +`disableOnAttributes` disable the typo tolerance feature on the specified attributes list. + +Any attributes defined in `disableOnAttributes` won't have their values matched by the typo tolerance. + +#### 3.1.2.1. Example + +Given `["title"]` as `disableOnAttributes` and the following document + +```json +{ + "id": 0, + "title": "Hey World" +} +``` + +The engine won't try to match query term with typos with values of the `title` attribute at search time to match documents. + +- Typing `Warld` won't bring the document as a candidate for the search results. + +### 3.1.3. `disableOnWords` + +- Type: Array of String +- Required: False +- Default: `[]` + +`disableOnWords` disable the typo tolerance feature on a list of search query terms. + +> This field is case insensitive since the document attributes values are lowercased and de-unicoded internally. + +#### 3.1.3.1. Example + +If `Javascript` is specified in `disableOnWords`, the engine won't apply the typo tolerance on the query term `Javascript` or `javascript` if typed at search time to match documents. + +### 3.1.4. `minWordSizeForTypos` + +- Type: Object +- Required: False + +#### 3.1.4.1. `minWordSizeForTypos` Object Definition + +| Field | Type | Required | +|----------------------------|-----------------|----------| +| [oneTypo](#3142-onetypo) | Integer | False | +| [twoTypos](#3143-twotypos) | Integer | False | + +#### 3.1.4.2. `oneTypo` + +- Type: Integer +- Required: False +- Default: `5` + +`oneTypo` customize the minimum size for a word to tolerate 1 typo. + +> Given the default value `5`, the search engine starts to apply typo tolerance on a query term if its length is at least equal to 5 characters. + +> See [2.1. Typos calculation section](#21-typos-calculation) + +##### 3.1.4.2.1 Example + +Given `5` as `oneTypo` and the following document + +```json +{ + "id": 0, + "title": "Hey World" +} +``` + +- Typing `World` with 1 typo, e.g. `Warld` will match `World`. It accepts 1 typo since `World` size is made of `5` chars. +- Typing `Hey` with 1 typo, e.g. `Hoy` won't match `Hey`. It accepts 0 typo since `Hey` size is made of `3` chars. + +#### 3.1.4.3. `twoTypos` + +- Type: Integer +- Required: False +- Default: `9` + +`twoTypos` customize the minimum size for a word to tolerate 2 typos. + +> Given the default value `9`, the search engine handles up to 2 typos on a query term if its length is at least equal to 9 characters. + +> See [2.1. Typos calculation section](#21-typos-calculation) + +##### 3.1.4.3.1. Example + +Given `3` for `oneTypo` and `5` as `twoTypos` and the following document + +```json +{ + "id": 0, + "title": "Hey World" +} +``` + +- Typing `World` with 2 typos, e.g. `Warrld` will match `World`. It accepts up to 2 typos since `World` size is made of `5` chars. +- Typing `Hey` with 1 typo, e.g. `Hoy` will match `Hey`. It accepts only 1 typo since `Hey` size is made of `3` chars. + +## 3.2. API Endpoints Definition + +### 3.2.1. Global Settings API Endpoints Definition + +`typoTolerance` is a sub-resource of `/indexes/:index_uid/settings`. + +See [Settings API](0123-settings-api.md). + +### 3.2.2. `indexes/:index_uid/settings/typo-tolerance` + +Manage the typo tolerance configuration for an index. + +#### 3.2.2.1. `GET` - `indexes/:index_uid/settings/typo-tolerance` + +Allow fetching the current definition of the typo tolerance feature for an index. + +`200` - Response body + +```json + { + "enabled": true, + "disableOnAttributes": [], + "disableOnWords": [], + "minWordSizeForTypos": { + "oneTypo": 5, + "twoTypos": 9 + } + } +``` + +All properties must be returned when the resource is retrieved. + +##### 3.2.2.1.2. Errors + +- 🔴 If the index does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. + +#### 3.2.2.2. `POST` - `indexes/:index_uid/settings/typo-tolerance` + +Allow customizing partially the settings of the typo tolerance feature for an index. + +Request payload + +```json +{ + "disableOnAttributes": [ + "title", + "description" + ], + "minWordSizeForTypos": 4 +} +``` + +`202 Accepted` - Example Response + +```json +{ + "uid": 42, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-03-01T18:39:29.228155Z" +} +``` + +##### 3.2.2.2.1. 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.2.2.2.2. 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. +- 🔴 Sending a different Content-Type than `application/json` returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. +- 🔴 Sending an empty payload returns a [missing_payload](0061-error-format-and-definitions.md#missing_payload) error. +- 🔴 Sending an invalid JSON payload returns a [malformed_payload](0061-error-format-and-definitions.md#malformed_payload) error. +- 🔴 Sending a value with a different type than `Boolean` for the `enabled` field returns an [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array of String` for the `disableOnAttributes` field returns an [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array of String` for the `disableOnWords` field returns an [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Integer` for `minWordSizeForTypos` object fields returns an [bad_request](0061-error-format-and-definitions.md#bad_request) error. + +###### 3.2.2.2.2.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.1. Response Definition](#32221-response-definition). + +> Otherwise, Meilisearch will create the index in a lazy way. See [3.2.2.2.3. Lazy Index Creation](#32223-lazy-index-creation). + +- 🔴 Sending invalid integer values for the `minWordSizeForTypos` object fields returns an [invalid_typo_tolerance_min_word_size_for_typos](0061-error-format-and-definitions.md#invalid_typo_min_word_size_for_typos) error. + +##### 3.2.2.2.3. Lazy Index Creation + +If the requested `index_uid` does not exist, and the authorization layer allows it (See [3.2.2.2.2.1. Async Errors](#322221-async-errors)), Meilisearch will create the index when the related asynchronous task resource is executed. See [3.2.2.2.1. Response Definition](#32221-response-definition). + +#### 3.2.2.3. `DELETE`- `indexes/:index_uid/settings/typo-tolerance` + +Allow resetting the typo tolerance feature to the default for an index. + +##### 3.2.2.3.1. Response Definition + +When the request is in a successful state, 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.2.2.3.2. Errors + +###### 3.2.2.3.2.1. Asynchronous Index Not Found Error + +- 🔴 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 in the related async `task` resource. See [3.2.2.3.1. Response Definition](#32231-response-definition). + +### 3.2.3. General Errors + +These errors apply to all endpoints described here. + +#### 3.2.3.1. Auth Errors + +The auth layer can return the following errors if Meilisearch is secured (a master-key is defined). + +- 🔴 Accessing this route without the `Authorization` header returns a [missing_authorization_header](0061-error-format-and-definitions.md#missing_authorization_header) error. +- 🔴 Accessing this route with a key that does not have permissions (i.e. other than the master-key) returns an [invalid_api_key](0061-error-format-and-definitions.md#invalid_api_key) error. + +## 2. Technical Details + +### 2.1. Typos Calculation + +The size of a query term triggers the typo tolerance feature. + +By default, a query term made of `5` characters can tolerate `1` typo, while a query term made of `9` characters can tolerate `2` typos. + +If a query term can be derived from a distance of one or two typos to be found in a document, it will be selected as a candidate. The number of typos found has an impact on the relevancy. + +#### 2.1.1 Typo On The First Character + +A query term having the first character considered as a typo will not count as `1` typo but as `2` typos. + +It permits to drastically reduce the search space in this case, thus speed-up the search response. + +#### 2.1.2. Clamping Typo On Concatened Query Terms + +The concatenation of two query terms is equal to 1 typo. + +e.g. If `Le tableau` is typed, the concatened string `Letableau` made of `9` letters can only have `1` typo instead of `2` since `1` typo is already counted by the concatenation. + +### 2.2. Typo Ranking Rule + +The `typo` ranking rule favors candidates with the least typos. That is, if a document is found with two typos, it will be ranked as less important than a document found with 1 typo. 0 typo is the most favorable case. + +## 3. Future Possibilities + +- Expose `typoTolerance` resource as a search parameter to override index settings. +- Add the possibility to disable the typo tolerance feature on all numeric fields. +- Add different modes of result matching for the typo feature. e.g. `default`/`min`/`strict` +- Replace `POST` to `PATCH` verb to allow partial edit of the settings and embrace REST API convention. +- Introduce synchronous `invalid_typo_tolerance_{fieldName}` error with a better error message than the one provided by serde. \ No newline at end of file diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 6e950714..cfbb8b2b 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -18,14 +18,14 @@ Meilisearch exposes 2 routes to perform searches: - 🔴 If the index does not exist, the API returns an [index_not_found](0061-error-format-and-definitions.md#index_not_found) error. -If the instance is secured by a master-key, the auth layer will return the following errors: +If the instance is secured by a master-key, the auth layer returns the following errors: - 🔴 Accessing these routes without the `Authorization` header returns a [missing_authorization_header](0061-error-format-and-definitions.md#missing_authorization_header) error. - 🔴 Accessing this route with a key that does not have permissions (i.e. other than the master-key) returns an [invalid_api_key](0061-error-format-and-definitions.md#invalid_api_key) error. `POST` HTTP verb errors: -- 🔴 Omitting Content-Type header returns a [missing_content_type](0061-error-format-and-definitions.md#missing_content_type) error. +- 🔴 Omitting the 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. - 🔴 Sending a different Content-Type than `application/json` returns an [invalid_content_type](0061-error-format-and-definitions.md#invalid_content_type) error. - 🔴 Sending an empty payload returns a [missing_payload](0061-error-format-and-definitions.md#missing_payload) error. @@ -55,7 +55,7 @@ If the instance is secured by a master-key, the auth layer will return the follo `q` contains the terms to search within the index documents. -- 🔴 Sending a value with a different type than `String` or `null` for `q` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `String` or `null` for `q` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. > When q isn't specified, Meilisearch performs a **placeholder search**. A placeholder search returns all searchable documents in an index, modified by any search parameters used and sorted by that index's custom ranking rules. If the index has no sort or custom ranking rules, the results are returned in the order of their internal database position. @@ -73,9 +73,9 @@ If the instance is secured by a master-key, the auth layer will return the follo 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). -- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `filter` will return an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. -- 🔴 Sending an invalid syntax for `filter` will return an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. -- 🔴 Sending a field not defined as a `filterableAttributes` for `filter` will return an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. +- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `filter` returns an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. +- 🔴 Sending an invalid syntax for `filter` returns an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. +- 🔴 Sending a field not defined as a `filterableAttributes` for `filter` returns an [invalid_filter](0061-error-format-and-definitions.md#invalid_filter) error. > See [Filter And Facet Behavior](0027-filter-and-facet-behavior.md) @@ -89,9 +89,9 @@ Attributes used as filter criteria must be added to the `filterableAttributes` l Attributes used as sort criteria must be added to the `sortableAttributes list of an index settings. See [Sortable Attributes Setting API](0123-sortable-attributes-setting-api.md). -- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `sort` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -- 🔴 Sending an invalid syntax for `sort` will return an [invalid_sort](0061-error-format-and-definitions.md#invalid_sort) error. -- 🔴 Sending a field not defined as a `sortableAttributes` for `sort` will return an [invalid_sort](0061-error-format-and-definitions.md#invalid_sort) error. +- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `sort` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending an invalid syntax for `sort` returns an [invalid_sort](0061-error-format-and-definitions.md#invalid_sort) error. +- 🔴 Sending a field not defined as a `sortableAttributes` for `sort` returns an [invalid_sort](0061-error-format-and-definitions.md#invalid_sort) error. > See [Sort](0055-sort.md) @@ -103,17 +103,17 @@ Attributes used as sort criteria must be added to the `sortableAttributes list o `facetsDistribution` permits to specify facets to be computed for the current search query. -It returns the number of documents matching the current search query for each given specified facet. +It returns the number of documents matching the current search query for each specified facet. This parameter can take two values: - An array of attributes: `facetsDistribution=["attributeA", "attributeB", …]` -- An asterisk `"*"` — this will return a count for all facets present in `filterableAttributes` +- An asterisk `"*"` — this returns a count for all facets present in `filterableAttributes` Attributes used in `facetsDistribution` must be added to the `filterableAttributes` list of an index settings. See [Filterable Attributes Setting API](0123-filterable-attributes-setting-api.md). -- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `facetsDistribution` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. -- 🔴 Sending a field not defined as a `filterableAttributes` for `facetsDistribution` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `facetsDistribution` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a field not defined as a `filterableAttributes` for `facetsDistribution` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. > See [Filter And Facet Behavior](0027-filter-and-facet-behavior.md) @@ -125,7 +125,7 @@ Attributes used in `facetsDistribution` must be added to the `filterableAttribut Sets the maximum number of documents to be returned by the current search query. -- 🔴 Sending a value with a different type than `Integer` or `null` for `limit` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Integer` or `null` for `limit` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. ##### 1.2.1.6 `offset` @@ -135,7 +135,7 @@ Sets the maximum number of documents to be returned by the current search query. Sets the starting point in the search results, effectively skipping over a given number of documents. -- 🔴 Sending a value with a different type than `Integer` or `null` for `offset` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Integer` or `null` for `offset` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. ##### 1.2.1.7 `attributesToRetrieve` @@ -149,7 +149,7 @@ If no value is specified, `attributesToRetrieve` uses the `displayedAttributes` > If an attribute has been removed from `displayedAttributes` index settings, `attributesToRetrieve` will silently ignore it and the field will not appear in the returned documents. -- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `attributesToRetrieve` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array of String`(POST), `String`(GET) or `null` for `attributesToRetrieve` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. ##### 1.2.1.8 `attributesToHighlight` @@ -163,7 +163,7 @@ When this parameter is set, returned documents include a `_formatted` object con If `"*"` is provided as a value: `attributesToHighlight=["*"]` all the attributes present in `attributesToRetrieve` will be assigned to `attributesToHighlight`. -- 🔴 Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToHighlight` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToHighlight` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. > See [_Formatted Field Behavior](0039-_formatted-field-behavior_.md) @@ -181,7 +181,7 @@ Optionally, indicating a custom crop length for any of the listed attributes is Instead of supplying individual attributes, it is possible to provide `["*"]` as a value: `attributesToCrop=["*"]`. This will crop the values of all attributes present in `attributesToRetrieve`. -- 🔴 Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToCrop` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Array[String]`(POST), `String`(GET) or `null` for `attributesToCrop` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. > See [_Formatted Field Behavior](0039-_formatted-field-behavior_.md) @@ -195,7 +195,7 @@ Configures the number of characters to keep on each side of the matching query t If `attributesToCrop` is not configured, `cropLength` has no effect on the returned results. -- 🔴 Sending a value with a different type than `Integer` or `null` for `cropLength` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Integer` or `null` for `cropLength` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. ##### 1.2.1.11 `matches` @@ -205,7 +205,7 @@ If `attributesToCrop` is not configured, `cropLength` has no effect on the retur Adds a `_matchesInfo` object to the search response that contains the location of each occurrence of queried terms across all fields. This is useful when more control is needed than offered by the built-in highlighting/cropping features. -- 🔴 Sending a value with a different type than `Boolean` or `null` for `matches` will return a [bad_request](0061-error-format-and-definitions.md#bad_request) error. +- 🔴 Sending a value with a different type than `Boolean` or `null` for `matches` returns a [bad_request](0061-error-format-and-definitions.md#bad_request) error. #### 1.2.2. Search response diff --git a/text/0123-settings-api.md b/text/0123-settings-api.md index 1a1b0a4f..5600da84 100644 --- a/text/0123-settings-api.md +++ b/text/0123-settings-api.md @@ -21,6 +21,7 @@ N/A | [stop-words](0123-stop-words-setting-api.md) | `stopWords` sub-resource API endpoints definition | | [synonyms](0123-synonyms-setting-api.md) | `synonyms` sub-resource API endpoints definition | | [distinct-attribute](0123-distinct-attribute-setting-api.md) | `distinctAttribute` sub-resource API endpoints definition | +| [typo-tolerance](0117-typo-tolerance-setting-api.md) | `typoTolerance` sub-resource API endpoints definition | Each setting is exposed as a sub-resource of the `indexes/:index_uid/settings` endpoints. e.g. The ranking rules setting of a Meilisearch index is exposed at `indexes/:index_uid/settings/ranking-rules`. @@ -46,6 +47,7 @@ Fetch the settings of a Meilisearch index. | `stopWords` | Array of String | true | | `synonyms` | Object | true | | `distinctAttribute` | String / `null` | true | +| `typo` | Object | true | The attributes ordering in the response payload is equivalent to the order described in the table above. @@ -69,6 +71,7 @@ Modify the settings of a Meilisearch index. | `stopWords` | Array of String / `null` | false | | `synonyms` | Object / `null` | false | | `distinctAttribute` | String / `null` | false | +| `typo` | Object | false | The request payload accepts partial definitions.