Merge pull request #1761 from meilisearch/v0.28-faceting-settings

v0.28: Faceting settings

.code-samples.meilisearch.yaml

@@ -181,6 +181,9 @@ update_settings_1: |-
           "twoTypos": 10
         },
         "disableOnAttributes": ["title"]
+      },
+      "faceting": {
+        "maxValuesPerFacet": 200
       }
     }'
 reset_settings_1: |-
@@ -948,3 +951,23 @@ 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 PATCH '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'
+settings_guide_faceting_1: |-
+  curl \
+    -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "maxValuesPerFacet": 5
+    }'

.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',

.vuepress/public/sample-template.yaml

@@ -146,3 +146,7 @@ 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: |-
+settings_guide_faceting_1: |-

learn/advanced/filtering_and_faceted_search.md

@@ -309,6 +309,10 @@ Using the `facets` search parameter adds `facetDistribution` to the returned obj
 }
 ```
 
+::: note
+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
 
 You can write a search query that gives you the distribution of `batman` movies per genre:

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
 
 <CodeSamples id="faceted_search_update_settings_1" />
 
+## 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:
+
+<CodeSamples id="settings_guide_faceting_1" />
+
 ## 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.

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)

reference/api/faceting.md

@@ -0,0 +1,98 @@
+# 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
+
+<RouteHighlighter method="GET" route="/indexes/{index_uid}/settings/faceting"/>
+
+Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+### Example
+
+<CodeSamples id="get_faceting_settings_1" />
+
+#### Response: `200 OK`
+
+```json
+{
+  "maxValuesPerFacet": 100
+}
+```
+
+### Returned fields
+
+#### `maxValuesPerFacet`
+
+Maximum number of facet values returned for each facet.
+
+## Update faceting settings
+
+<RouteHighlighter method="PATCH" route="/indexes/{index_uid}/settings/faceting"/>
+
+Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+### Body
+
+#### `maxValuesPerFacet`
+
+**Type:** integer
+**Default value:** `100`
+
+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.
+
+::: note
+Setting `maxValuesPerFacet` to a high value might negatively impact performance.
+:::
+
+#### Example
+
+<CodeSamples id="update_faceting_settings_1" />
+
+#### Response: `202 Accepted`
+
+```json
+{
+  "taskUid": 1,
+  "indexUid": "books",
+  "status": "enqueued",
+  "type": "settingsUpdate",
+  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
+}
+```
+
+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
+
+Reset an index's faceting settings to their default value. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+#### Example
+
+<CodeSamples id="reset_faceting_settings_1" />
+
+#### Response: `200 OK`
+
+```json
+{
+  "taskUid": 1,
+  "indexUid": "books",
+  "status": "enqueued",
+  "type": "settingsUpdate",
+  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
+}
+```
+
+You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).