From cd4c05f846221e142cbf3fad7a654aafdd4dad49 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 5 Dec 2024 18:12:10 +0100 Subject: [PATCH 1/4] add prefix and facet search opt-outs --- .code-samples.meilisearch.yaml | 22 ++++ reference/api/settings.mdx | 197 +++++++++++++++++++++++++++++++ reference/errors/error_codes.mdx | 14 ++- 3 files changed, 232 insertions(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 60c51a7ff..17f965ae6 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1201,6 +1201,28 @@ update_proximity_precision_settings_1: |- reset_proximity_precision_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision' +get_facet_search_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' +update_facet_search_settings_1: |- + curl \ + -X PUT 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' \ + -H 'Content-Type: application/json' \ + --data-binary 'false' +reset_facet_search_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' +get_prefix_search_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' +update_prefix_search_settings_1: |- + curl \ + -X PUT 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' \ + -H 'Content-Type: application/json' \ + --data-binary '"disabled"' +reset_prefix_search_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' index_settings_tutorial_api_get_setting_1: |- curl \ -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes' diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index db8ab19f3..3bc0f60a3 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -59,6 +59,8 @@ By default, the settings object looks like this. All fields are modifiable. "maxTotalHits": 1000 }, "proximityPrecision": "byWord", + "facetSearch": true, + "prefixSearch": "indexingTime", "searchCutoffMs": null } ``` @@ -126,6 +128,8 @@ Get the settings of an index. "maxTotalHits": 1000 }, "proximityPrecision": "byWord", + "facetSearch": true, + "prefixSearch": "indexingTime", "searchCutoffMs": null } ``` @@ -159,6 +163,8 @@ If the provided index does not exist, it will be created. | **[`filterableAttributes`](#filterable-attributes)** | Array of strings | Empty | Attributes to use as filters and facets | | **[`pagination`](#pagination)** | Object | [Default object](#pagination-object) | Pagination settings | | **[`proximityPrecision`](#proximity-precision)** | String | `"byWord"` | Precision level when calculating the proximity ranking rule | +| **[`facetSearch`](#facet-search)** | Boolean | `true` | Enable or disable [facet search](/reference/api/facet_search) functionality | +| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When and if Meilisearch should return results only matching the beginning of query | | **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attribute",`
`"sort",`
`"exactness"]` | List of ranking rules in order of importance | | **[`searchableAttributes`](#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance | | **[`searchCutoffMs`](#search-cutoff)** | Integer | `null`, or 1500ms | Maximum duration of a search query | @@ -1141,6 +1147,197 @@ Reset an index's proximity precision setting to its default value. You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +## Facet search + +Processing filterable attributes for facet search is a resource-intensive operation. This feature is enabled by default, but disabling it may speed up indexing. + +`facetSearch` accepts a single Boolean value. If set to `false`, it disables facet search for the whole index. Meilisearch returns an error if you try to access the `/facet-search` endpoint when facet search is disabled. + +### Get facet search settings + + + +Get the facet search settings of an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `200 OK` + +```json +{ + "facetSearch": true +} +``` + +### Update facet search settings + + + +Update the facet search settings for an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Body + +``` + +``` + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_NAME", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:33:18.523881Z" +} +``` + +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +### Reset facet search settings + +Reset an index's facet search settings to its default value. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_NAME", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:35:33.723983Z" +} +``` + +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +## Prefix search + +Prefix search is the process through which Meilisearch matches documents that begin with a specific query, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default. + +Use `prefixSearch` to change how prefix search works. It accepts one of the following strings: + +- `"indexingTime"`: calculate prefix search during indexing. This is the default behavior +- `"disabled"`: do not calculate prefix search. May speed up indexing, but will severely impact search result relevancy + +### Get prefix search settings + + + +Get the prefix search settings of an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `200 OK` + +```json +{ + "prefixSearch": "indexingTime" +} +``` + +### Update prefix search settings + + + +Update the prefix search settings for an index. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Body + +``` +"indexingTime" | "disabled" +``` + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_NAME", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:33:18.523881Z" +} +``` + +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + +### Reset prefix search settings + +Reset an index's facet search settings to its default value. + +#### Path parameters + +| Name | Type | Description | +| :---------------- | :----- | :--------------------------------------------------------------------- | +| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index | + +#### Example + + + +##### Response: `202 Accepted` + +```json +{ + "taskUid": 1, + "indexUid": "INDEX_NAME", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2024-07-19T22:35:33.723983Z" +} +``` + +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). + ## Ranking rules Ranking rules are built-in rules that rank search results according to certain criteria. They are applied in the same order in which they appear in the `rankingRules` array. diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index 4b96cfb2d..4fe977280 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -35,6 +35,10 @@ The requested document can't be retrieved. Either it doesn't exist, or the datab An error occurred during the dump creation process. The task was aborted. +## `facet_search_disabled` + +The [`/facet-search`](/reference/api/facet_search) route has been queried while [the `facetSearch` index setting](/reference/api/settings#facet-search) is set to `false`. + ## `immutable_api_key_actions` The [`actions`](/reference/api/keys#actions) field of an API key cannot be modified. @@ -93,7 +97,7 @@ The requested index already has a primary key that [cannot be changed](/learn/ge ## `internal` - Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary. +Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary. ## `invalid_api_key` @@ -296,6 +300,10 @@ The [`limit`](/reference/api/search#limit) parameter is invalid. It should be an The [`locales`](/reference/api/search#query-locales) parameter is invalid. +## `invalid_settings_facet_search` + +The [`facetSearch`](/reference/api/settings#facet-search) index setting value is invalid. + ## `invalid_settings_localized_attributes` The [`localizedAttributes`](/reference/api/settings#localized-attributes) index setting value is invalid. @@ -308,6 +316,10 @@ The [`matchingStrategy`](/reference/api/search#matching-strategy) parameter is i The [`offset`](/reference/api/search#offset) parameter is invalid. It should be an integer. +## `invalid_settings_prefix_search` + +The [`prefixSearch`](/reference/api/settings#prefix-search) index setting value is invalid. + ## `invalid_search_page` The [`page`](/reference/api/search#page) parameter is invalid. It should be an integer. From 4758e8f62e606dfe181d4f7ab72ff757c2d03587 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 5 Dec 2024 18:53:15 +0100 Subject: [PATCH 2/4] add DELETE routehighlighter component --- reference/api/settings.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index 3bc0f60a3..8f26bae61 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -1123,6 +1123,8 @@ You can use the returned `taskUid` to get more details on [the status of the tas Reset an index's proximity precision setting to its default value. + + #### Path parameters | Name | Type | Description | @@ -1215,6 +1217,8 @@ You can use the returned `taskUid` to get more details on [the status of the tas ### Reset facet search settings + + Reset an index's facet search settings to its default value. #### Path parameters @@ -1312,6 +1316,8 @@ You can use the returned `taskUid` to get more details on [the status of the tas ### Reset prefix search settings + + Reset an index's facet search settings to its default value. #### Path parameters From a39fb06c572c09bb38b77f85f02c9c7db7045076 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 12 Dec 2024 15:28:41 +0100 Subject: [PATCH 3/4] improve wording --- .code-samples.meilisearch.yaml | 12 ++++++------ reference/api/settings.mdx | 20 ++++++++++---------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 17f965ae6..4220f2ce5 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1203,26 +1203,26 @@ reset_proximity_precision_settings_1: |- -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision' get_facet_search_settings_1: |- curl \ - -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' + -X GET 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' update_facet_search_settings_1: |- curl \ - -X PUT 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' \ + -X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' \ -H 'Content-Type: application/json' \ --data-binary 'false' reset_facet_search_settings_1: |- curl \ - -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/facet-search' + -X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' get_prefix_search_settings_1: |- curl \ - -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' + -X GET 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' update_prefix_search_settings_1: |- curl \ - -X PUT 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' \ + -X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' \ -H 'Content-Type: application/json' \ --data-binary '"disabled"' reset_prefix_search_settings_1: |- curl \ - -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/prefix-search' + -X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' index_settings_tutorial_api_get_setting_1: |- curl \ -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes' diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index 8f26bae61..07b316e3b 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -164,7 +164,7 @@ If the provided index does not exist, it will be created. | **[`pagination`](#pagination)** | Object | [Default object](#pagination-object) | Pagination settings | | **[`proximityPrecision`](#proximity-precision)** | String | `"byWord"` | Precision level when calculating the proximity ranking rule | | **[`facetSearch`](#facet-search)** | Boolean | `true` | Enable or disable [facet search](/reference/api/facet_search) functionality | -| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When and if Meilisearch should return results only matching the beginning of query | +| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When Meilisearch should return results only matching the beginning of query | | **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`
`"typo",`
`"proximity",`
`"attribute",`
`"sort",`
`"exactness"]` | List of ranking rules in order of importance | | **[`searchableAttributes`](#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance | | **[`searchCutoffMs`](#search-cutoff)** | Integer | `null`, or 1500ms | Maximum duration of a search query | @@ -1121,10 +1121,10 @@ You can use the returned `taskUid` to get more details on [the status of the tas ### Reset proximity precision settings -Reset an index's proximity precision setting to its default value. - +Reset an index's proximity precision setting to its default value. + #### Path parameters | Name | Type | Description | @@ -1213,13 +1213,13 @@ Update the facet search settings for an index. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). ### Reset facet search settings -Reset an index's facet search settings to its default value. +Reset an index's facet search to its default settings. #### Path parameters @@ -1243,11 +1243,11 @@ Reset an index's facet search settings to its default value. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). ## Prefix search -Prefix search is the process through which Meilisearch matches documents that begin with a specific query, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default. +Prefix search is the process through which Meilisearch matches documents that begin with a specific query term, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default. Use `prefixSearch` to change how prefix search works. It accepts one of the following strings: @@ -1312,13 +1312,13 @@ Update the prefix search settings for an index. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). ### Reset prefix search settings -Reset an index's facet search settings to its default value. +Reset an index's prefix search to its default settings. #### Path parameters @@ -1342,7 +1342,7 @@ Reset an index's facet search settings to its default value. } ``` -You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). +Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task). ## Ranking rules From 74788bfb42dfb58d5e91c1bb54826166d62e2814 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 12 Dec 2024 15:29:32 +0100 Subject: [PATCH 4/4] use consistent index uid placeholder --- reference/api/settings.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/api/settings.mdx b/reference/api/settings.mdx index 07b316e3b..85de71c49 100644 --- a/reference/api/settings.mdx +++ b/reference/api/settings.mdx @@ -1206,7 +1206,7 @@ Update the facet search settings for an index. ```json { "taskUid": 1, - "indexUid": "INDEX_NAME", + "indexUid": "INDEX_UID", "status": "enqueued", "type": "settingsUpdate", "enqueuedAt": "2024-07-19T22:33:18.523881Z" @@ -1236,7 +1236,7 @@ Reset an index's facet search to its default settings. ```json { "taskUid": 1, - "indexUid": "INDEX_NAME", + "indexUid": "INDEX_UID", "status": "enqueued", "type": "settingsUpdate", "enqueuedAt": "2024-07-19T22:35:33.723983Z" @@ -1305,7 +1305,7 @@ Update the prefix search settings for an index. ```json { "taskUid": 1, - "indexUid": "INDEX_NAME", + "indexUid": "INDEX_UID", "status": "enqueued", "type": "settingsUpdate", "enqueuedAt": "2024-07-19T22:33:18.523881Z" @@ -1335,7 +1335,7 @@ Reset an index's prefix search to its default settings. ```json { "taskUid": 1, - "indexUid": "INDEX_NAME", + "indexUid": "INDEX_UID", "status": "enqueued", "type": "settingsUpdate", "enqueuedAt": "2024-07-19T22:35:33.723983Z"