From a5c2e63a88b5176abe990a10acd222d008371bf7 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 Jun 2022 18:17:26 +0200 Subject: [PATCH 01/13] faceting settings: API reference scaffolding --- reference/api/faceting.md | 91 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 reference/api/faceting.md diff --git a/reference/api/faceting.md b/reference/api/faceting.md new file mode 100644 index 0000000000..3f06be1066 --- /dev/null +++ b/reference/api/faceting.md @@ -0,0 +1,91 @@ +# Faceting + +_Child route of the [settings route](/reference/api/settings.md)._ + +This route allows you to configure the faceting settings for an index. + +faceting settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. + +To learn more about filtering and faceting, refer to our [dedicated guide](/learn/advanced/filtering_and_faceted_search.md). + +::: warning +Updating the settings means overwriting the default settings of Meilisearch. You can reset to default values using the `DELETE` routes. +::: + +## Get faceting settings + + + +Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Example + + + +#### Response: `200 OK` + +```json +{ + +} +``` + +### Returned fields + +#### `field_name` + +[field explanation] + +## Update faceting settings + + + +Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +### Body + +#### `field_name` + +[field explanation] + +#### Example + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:56:44.991039Z" +} +``` + +You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). + +## Reset faceting settings + +Reset an index's faceting settings to their default value. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. + +#### Example + + + +#### Response: `200 OK` + +```json +{ + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:53:32.863107Z" +} +``` + +You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). + + From 1beedf37d01bbbaabd78a056c891a19b900b0787 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 27 Jun 2022 19:27:38 +0200 Subject: [PATCH 02/13] faceting settings: add new API reference page --- .code-samples.meilisearch.yaml | 16 ++++++ .vuepress/public/sample-template.yaml | 3 + reference/api/faceting.md | 41 +++++++------- reference/api/settings.md | 80 ++++++++++++++------------- 4 files changed, 84 insertions(+), 56 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 047cb60b9f..154bededf4 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -183,6 +183,9 @@ update_settings_1: |- "twoTypos": 10 }, "disableOnAttributes": ["title"] + }, + "faceting": { + "maxValuesPerFacet": 200 } }' reset_settings_1: |- @@ -958,3 +961,16 @@ getting_started_typo_tolerance: |- --data-binary '{ "minWordSizeForTypos": { "oneTypo": 4 } }' +get_faceting_settings_1: |- + curl \ + -X GET 'http://localhost:7700/indexes/books/settings/faceting' +update_faceting_settings_1: |- + curl \ + -X POST 'http://localhost:7700/indexes/books/settings/faceting' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxValuesPerFacet": 2 + }' +reset_faceting_settings_1: |- + curl \ + -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' \ No newline at end of file diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 8b52eec657..00f2e97787 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -146,3 +146,6 @@ updating_guide_retrieve_documents_old: |- updating_guide_update_settings_old: |- updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- +get_faceting_settings_1: |- +update_faceting_settings_1: |- +reset_faceting_settings_1: |- \ No newline at end of file diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 3f06be1066..fd6c6c1ba0 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -26,41 +26,46 @@ Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/in ```json { - + "maxValuesPerFacet": 100 } ``` ### Returned fields -#### `field_name` +#### `maxValuesPerFacet` -[field explanation] +Maximum number of facet values returned for each facet. ## Update faceting settings - + Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required. ### Body -#### `field_name` +#### `maxValuesPerFacet` + +**Type:** integer +**Default value:** `100` + +Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. -[field explanation] +For example, if a query's search results contain a total of three values for a `colors` facet—`blue`, `green`, and `red`—setting `maxValuesPerFacet` to `2` causes Meilisearch to return only the `blue` and `green` in the response body's `facetDistribution` object. #### Example -#### Response: `200 OK` +#### Response: `202 Accepted` ```json { - "uid": 1, - "indexUid": "books", - "status": "enqueued", - "type": "settingsUpdate", - "enqueuedAt": "2022-04-14T20:56:44.991039Z" + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:56:44.991039Z" } ``` @@ -78,14 +83,12 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le ```json { - "uid": 1, - "indexUid": "books", - "status": "enqueued", - "type": "settingsUpdate", - "enqueuedAt": "2022-04-14T20:53:32.863107Z" + "uid": 1, + "indexUid": "books", + "status": "enqueued", + "type": "settingsUpdate", + "enqueuedAt": "2022-04-14T20:53:32.863107Z" } ``` You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). - - diff --git a/reference/api/settings.md b/reference/api/settings.md index 2d22e9b45b..78dd471bc3 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -30,17 +30,18 @@ Get the settings of an index. The index [`uid`](/learn/core_concepts/indexes.md# ### Response body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings in this guide.](/learn/configuration/settings.md) @@ -94,10 +95,13 @@ List the settings. "minWordSizeForTypos": { "oneTypo": 5, "twoTypos": 10 - }, - "disableOnWords": [], - "disableOnAttributes": [] - } + }, + "disableOnWords": [], + "disableOnAttributes": [] + }, + "faceting": { + "maxValuesPerFacet": 100 + } } ``` @@ -117,17 +121,18 @@ If the provided index does not exist, it will be created. ### Body -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | ### Example @@ -155,17 +160,18 @@ Reset the settings of an index. The index [`uid`](/learn/core_concepts/indexes.m All settings will be reset to their default value. -| Variable | Type | Description | Default value | -| ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | -| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | -| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | -| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | -| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | -| **synonyms** | Object | List of associated words treated similarly | `{}` | -| **typoTolerance** | Object | Typo tolerance settings | `{}` | +| Variable | Type | Description | Default value | +| ------------------------ | --------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | +| **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | +| **faceting** | Object | Faceting settings | `{}` | +| **filterableAttributes** | [Strings] | Attributes to use as [filters and facets](/learn/advanced/filtering_and_faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | +| **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | +| **sortableAttributes** | [Strings] | Attributes to use when [sorting](/learn/advanced/sorting.md) search results | `[]` | +| **stopWords** | [Strings] | List of words ignored by Meilisearch when present in search queries | `[]` | +| **synonyms** | Object | List of associated words treated similarly | `{}` | +| **typoTolerance** | Object | Typo tolerance settings | `{}` | [Learn more about the settings](/learn/configuration/settings.md). #### Example From cfe49f5ed0caef05cb530f788e04edab27beb20e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 12:43:43 +0200 Subject: [PATCH 03/13] faceting: add API reference to sidebar menu --- .vuepress/config.js | 1 + reference/api/faceting.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index 395bd548d8..5a0db71d9e 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -323,6 +323,7 @@ module.exports = { }, '/reference/api/displayed_attributes', '/reference/api/distinct_attribute', + '/reference/api/faceting', '/reference/api/filterable_attributes', '/reference/api/ranking_rules', '/reference/api/searchable_attributes', diff --git a/reference/api/faceting.md b/reference/api/faceting.md index fd6c6c1ba0..bafc08eb3b 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -4,7 +4,7 @@ _Child route of the [settings route](/reference/api/settings.md)._ This route allows you to configure the faceting settings for an index. -faceting settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. +Faceting settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. To learn more about filtering and faceting, refer to our [dedicated guide](/learn/advanced/filtering_and_faceted_search.md). @@ -51,7 +51,7 @@ Partially update the faceting settings for an index. The index [`uid`](/learn/co Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. -For example, if a query's search results contain a total of three values for a `colors` facet—`blue`, `green`, and `red`—setting `maxValuesPerFacet` to `2` causes Meilisearch to return only the `blue` and `green` in the response body's `facetDistribution` object. +For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. #### Example From 0a8faa653bbf893a44a2b9684d570fa9b690d583 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 28 Jun 2022 12:46:36 +0200 Subject: [PATCH 04/13] faceting: add newline at end of files --- .code-samples.meilisearch.yaml | 2 +- .vuepress/public/sample-template.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 154bededf4..01c25955c9 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -973,4 +973,4 @@ update_faceting_settings_1: |- }' reset_faceting_settings_1: |- curl \ - -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' \ No newline at end of file + -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 00f2e97787..44f0a2d788 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -148,4 +148,4 @@ updating_guide_add_documents_old: |- getting_started_typo_tolerance: |- get_faceting_settings_1: |- update_faceting_settings_1: |- -reset_faceting_settings_1: |- \ No newline at end of file +reset_faceting_settings_1: |- From 3ffacec1198ae89b4c4ce4b2f9307aaf5acac725 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:11:46 +0200 Subject: [PATCH 05/13] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- .code-samples.meilisearch.yaml | 2 +- reference/api/faceting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 01c25955c9..d121406c65 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -966,7 +966,7 @@ get_faceting_settings_1: |- -X GET 'http://localhost:7700/indexes/books/settings/faceting' update_faceting_settings_1: |- curl \ - -X POST 'http://localhost:7700/indexes/books/settings/faceting' \ + -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \ -H 'Content-Type: application/json' \ --data-binary '{ "maxValuesPerFacet": 2 diff --git a/reference/api/faceting.md b/reference/api/faceting.md index bafc08eb3b..691680214d 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -83,7 +83,7 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From bb77d2d5b2861e69858328d2b342784f215d60ec Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:12:00 +0200 Subject: [PATCH 06/13] Update reference/api/faceting.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/faceting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 691680214d..1469d14598 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -61,7 +61,7 @@ For example, suppose a query's search results contain a total of three values fo ```json { - "uid": 1, + "taskUid": 1, "indexUid": "books", "status": "enqueued", "type": "settingsUpdate", From 100c17a3fa46d214fc5d4ddaa998e6974409fc77 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:15:45 +0200 Subject: [PATCH 07/13] faceting settings: address review feedback --- reference/api/faceting.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 1469d14598..0baa25aad8 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -53,6 +53,10 @@ Configure the maximum number of facet values returned for each facet. Values are For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. +::: note +Settings `maxValuesPerFacet` to a high value might negatively impact performance. +::: + #### Example From 456eec5bc8dd568a6a9339d87f5d18975bb565f0 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 29 Jun 2022 16:16:07 +0200 Subject: [PATCH 08/13] faceting settings: address review feedback --- reference/api/settings.md | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/api/settings.md b/reference/api/settings.md index 78dd471bc3..4d62369e92 100644 --- a/reference/api/settings.md +++ b/reference/api/settings.md @@ -6,6 +6,7 @@ These are the reference pages for the child routes: - [Displayed attributes](/reference/api/displayed_attributes.md) - [Distinct attribute](/reference/api/distinct_attribute.md) +- [Faceting](/reference/api/faceting.md) - [Filterable attributes](/reference/api/filterable_attributes.md) - [Ranking rules](/reference/api/ranking_rules.md) - [Searchable attributes](/reference/api/searchable_attributes.md) From 4c6a5f9b447ce92e5b4cfb19dd61a497f727c9b4 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:45:54 +0200 Subject: [PATCH 09/13] Apply suggestions from code review Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/faceting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index 0baa25aad8..ef5622226f 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -54,7 +54,7 @@ Configure the maximum number of facet values returned for each facet. Values are For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object. ::: note -Settings `maxValuesPerFacet` to a high value might negatively impact performance. +Setting `maxValuesPerFacet` to a high value might negatively impact performance. ::: #### Example @@ -73,7 +73,7 @@ Settings `maxValuesPerFacet` to a high value might negatively impact performance } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). ## Reset faceting settings @@ -95,4 +95,4 @@ Reset an index's faceting settings to their default value. The index [`uid`](/le } ``` -You can use the returned `uid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). +You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task). From da8c4a68caa628ece2a3bde8defae2aa5cd38706 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 12:56:03 +0200 Subject: [PATCH 10/13] faceting settings: add note to faceting guide --- learn/advanced/filtering_and_faceted_search.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 5c7e83c362..0d12f434d7 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -316,6 +316,10 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne `exhaustiveFacetsCount` is not currently implemented in and will always return `false`. ::: +::: note +By default, `facetDistribution` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). +::: + ##### Example You can write a search query that gives you the distribution of `batman` movies per genre: From c93be15c2bdef6b8a307e158ac816734c046c54e Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 30 Jun 2022 13:31:23 +0200 Subject: [PATCH 11/13] Update learn/advanced/filtering_and_faceted_search.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- learn/advanced/filtering_and_faceted_search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 0d12f434d7..df47fc7dc4 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -317,7 +317,7 @@ Using the `facetsDistribution` search parameter adds two new keys to the returne ::: ::: note -By default, `facetDistribution` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). +By default, `facets` returns a maximum of 100 facet values for each faceted field. You can change this value using the `maxValuesPerFacet` property of the [`faceting` index settings](/reference/api/faceting.md). ::: ##### Example From be6cd5cb9b77ae0a7519a42cd9deda6ba713a420 Mon Sep 17 00:00:00 2001 From: Maryam <90181761+maryamsulemani97@users.noreply.github.com> Date: Mon, 4 Jul 2022 16:39:59 +0400 Subject: [PATCH 12/13] v0.28: Add faceting to core concepts+index settings (#1767) * add faceting to index settings+core concepts * Update learn/configuration/settings.md * Update settings.md * Update learn/core_concepts/indexes.md * Update learn/core_concepts/indexes.md Co-authored-by: gui machiavelli Co-authored-by: gui machiavelli --- .code-samples.meilisearch.yaml | 7 +++++++ .vuepress/public/sample-template.yaml | 1 + learn/configuration/settings.md | 17 +++++++++++++++++ learn/core_concepts/indexes.md | 9 +++++++++ 4 files changed, 34 insertions(+) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 551d499812..821d99901f 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -972,3 +972,10 @@ update_faceting_settings_1: |- reset_faceting_settings_1: |- curl \ -X DELETE 'http://localhost:7700/indexes/books/settings/faceting' +settings_guide_faceting_1: |- + curl \ + -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "maxValuesPerFacet": 5 + }' diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 1bd841fb4a..b2b8c439bc 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -149,3 +149,4 @@ getting_started_typo_tolerance: |- get_faceting_settings_1: |- update_faceting_settings_1: |- reset_faceting_settings_1: |- +settings_guide_faceting_1: |- diff --git a/learn/configuration/settings.md b/learn/configuration/settings.md index a0380f432d..b31a0094f2 100644 --- a/learn/configuration/settings.md +++ b/learn/configuration/settings.md @@ -7,6 +7,7 @@ This page describes the **index-level settings** available in Meilisearch and ho | **[displayedAttributes](/learn/configuration/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents | | **[distinctAttribute](/learn/configuration/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` | | **[filterableAttributes](/learn/configuration/settings.md#filterable-attributes)** | List of attributes that can be used for filtering | `null` | +| **[faceting](/learn/advanced/filtering_and_faceted_search.md)** | Faceting settings | `{}` | **[rankingRules](/learn/configuration/settings.md#ranking-rules)** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#built-in-rules) | | **[searchableAttributes](/learn/configuration/settings.md#searchable-attributes)** | Fields in which to search for matching query words sorted by order of importance | All attributes found in the documents | | | **[sortableAttributes](/learn/configuration/settings.md#sortable-attributes)** | List of attributes to use when sorting search results | `[]` | @@ -95,6 +96,22 @@ To be able to filter search results on `director` and `genres` in a movie databa +## Faceting + +The faceting settings of an index. Facets are specific use-cases of filters that can be used to refine search results. + +::: tip +Like filters, you need to add your facets to [`filterableAttributes`](/reference/api/filterable_attributes.md#update-filterable-attributes) in order to use the [`filter`](/reference/api/search.md#filter) search parameter. +::: + +[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md) + +#### Example + +The following code sample will return a maximum of `5` facet values for each facet in the `movies` index: + + + ## Ranking rules Built-in ranking rules that **ensure relevancy in search results**. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance. diff --git a/learn/core_concepts/indexes.md b/learn/core_concepts/indexes.md index 9eb84d248a..70936859f5 100644 --- a/learn/core_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -58,6 +58,7 @@ You can customize the following index settings: - [Stop words](#stop-words) - [Displayed and searchable attributes](#displayed-and-searchable-attributes) - [Typo tolerance](#typo-tolerance) +- [Faceting](#faceting) To change index settings, use the [update settings endpoint](/reference/api/settings.md#update-settings) or any of the [child routes](/reference/api/settings.md#all-settings). @@ -129,3 +130,11 @@ Typo tolerance is a built-in feature that helps you find relevant results even w You can update the typo tolerance settings using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update typo tolerance endpoint](/reference/api/typo_tolerance.md#update-typo-tolerance). [Learn more about typo tolerance](/learn/configuration/typo_tolerance.md) + +### Faceting + +Facets are a specific use-case of filters in Meilisearch: whether something is a facet or filter depends on your UI and UX design. Like filters, you need to add your facets to [`filterableAttributes`](/reference/api/filterable_attributes.md#update-filterable-attributes), then make a search query using the [`filter` search parameter](/reference/api/search.md#filter). + +By default, Meilisearch returns `100` facet values for each faceted field. You can change this using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update faceting settings endpoint](/reference/api/faceting.md#update-faceting-settings). + +[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md) From 8fa84da4ae53782156864dfc6f45bbf628364a85 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 6 Jul 2022 12:45:00 +0200 Subject: [PATCH 13/13] Update reference/api/faceting.md Co-authored-by: Guillaume Mourier --- reference/api/faceting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/faceting.md b/reference/api/faceting.md index ef5622226f..a2d32ad122 100644 --- a/reference/api/faceting.md +++ b/reference/api/faceting.md @@ -49,7 +49,7 @@ Partially update the faceting settings for an index. The index [`uid`](/learn/co **Type:** integer **Default value:** `100` -Configure the maximum number of facet values returned for each facet. Values are alphabetically sorted. +Configure the maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order. For example, suppose a query's search results contain a total of three values for a `colors` facet: `blue`, `green`, and `red`. If you set `maxValuesPerFacet` to `2`, Meilisearch will only return `blue` and `green` in the response body's `facetDistribution` object.