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 <[email protected]>

Co-authored-by: gui machiavelli <[email protected]>

Author: maryamsulemani97

.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
+    }'

.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: |-

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)