diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml
index 6960627c99..821d99901f 100644
--- a/.code-samples.meilisearch.yaml
+++ b/.code-samples.meilisearch.yaml
@@ -189,6 +189,9 @@ update_settings_1: |-
"twoTypos": 10
},
"disableOnAttributes": ["title"]
+ },
+ "faceting": {
+ "maxValuesPerFacet": 200
}
}'
reset_settings_1: |-
@@ -956,3 +959,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
+ }'
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/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml
index fa0fae984f..b2b8c439bc 100644
--- a/.vuepress/public/sample-template.yaml
+++ b/.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: |-
diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md
index 7a057de53f..7e22260db9 100644
--- a/learn/advanced/filtering_and_faceted_search.md
+++ b/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:
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)
diff --git a/reference/api/faceting.md b/reference/api/faceting.md
new file mode 100644
index 0000000000..a2d32ad122
--- /dev/null
+++ b/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
+
+
+
+Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
+
+### Example
+
+
+
+#### Response: `200 OK`
+
+```json
+{
+ "maxValuesPerFacet": 100
+}
+```
+
+### Returned fields
+
+#### `maxValuesPerFacet`
+
+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
+
+#### `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
+
+
+
+#### 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
+
+
+
+#### 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).
diff --git a/reference/api/settings.md b/reference/api/settings.md
index 23ea867009..07d3f26745 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)
@@ -30,17 +31,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 +96,13 @@ List the settings.
"minWordSizeForTypos": {
"oneTypo": 5,
"twoTypos": 10
- },
- "disableOnWords": [],
- "disableOnAttributes": []
- }
+ },
+ "disableOnWords": [],
+ "disableOnAttributes": []
+ },
+ "faceting": {
+ "maxValuesPerFacet": 100
+ }
}
```
@@ -117,17 +122,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 +161,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