Skip to content

Commit 5dd44ec

Browse files
bors[bot]guimachiavellimaryamsulemani97
authored
Merge #1761
1761: v0.28: Faceting settings r=guimachiavelli a=guimachiavelli Closes #1704 Co-authored-by: gui machiavelli <[email protected]> Co-authored-by: gui machiavelli <[email protected]> Co-authored-by: Maryam <[email protected]>
2 parents 700e37d + 8fa84da commit 5dd44ec

File tree

8 files changed

+200
-37
lines changed

8 files changed

+200
-37
lines changed

‎.code-samples.meilisearch.yaml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,9 @@ update_settings_1: |-
181181
"twoTypos": 10
182182
},
183183
"disableOnAttributes": ["title"]
184+
},
185+
"faceting": {
186+
"maxValuesPerFacet": 200
184187
}
185188
}'
186189
reset_settings_1: |-
@@ -948,3 +951,23 @@ getting_started_typo_tolerance: |-
948951
--data-binary '{
949952
"minWordSizeForTypos": { "oneTypo": 4 }
950953
}'
954+
get_faceting_settings_1: |-
955+
curl \
956+
-X GET 'http://localhost:7700/indexes/books/settings/faceting'
957+
update_faceting_settings_1: |-
958+
curl \
959+
-X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \
960+
-H 'Content-Type: application/json' \
961+
--data-binary '{
962+
"maxValuesPerFacet": 2
963+
}'
964+
reset_faceting_settings_1: |-
965+
curl \
966+
-X DELETE 'http://localhost:7700/indexes/books/settings/faceting'
967+
settings_guide_faceting_1: |-
968+
curl \
969+
-X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \
970+
-H 'Content-Type: application/json' \
971+
--data-binary '{
972+
"maxValuesPerFacet": 5
973+
}'

‎.vuepress/config.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -323,6 +323,7 @@ module.exports = {
323323
},
324324
'/reference/api/displayed_attributes',
325325
'/reference/api/distinct_attribute',
326+
'/reference/api/faceting',
326327
'/reference/api/filterable_attributes',
327328
'/reference/api/ranking_rules',
328329
'/reference/api/searchable_attributes',

‎.vuepress/public/sample-template.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,3 +146,7 @@ updating_guide_retrieve_documents_old: |-
146146
updating_guide_update_settings_old: |-
147147
updating_guide_add_documents_old: |-
148148
getting_started_typo_tolerance: |-
149+
get_faceting_settings_1: |-
150+
update_faceting_settings_1: |-
151+
reset_faceting_settings_1: |-
152+
settings_guide_faceting_1: |-

‎learn/advanced/filtering_and_faceted_search.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,10 @@ Using the `facets` search parameter adds `facetDistribution` to the returned obj
309309
}
310310
```
311311

312+
::: note
313+
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).
314+
:::
315+
312316
##### Example
313317

314318
You can write a search query that gives you the distribution of `batman` movies per genre:

‎learn/configuration/settings.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This page describes the **index-level settings** available in Meilisearch and ho
77
| **[displayedAttributes](/learn/configuration/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents |
88
| **[distinctAttribute](/learn/configuration/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` |
99
| **[filterableAttributes](/learn/configuration/settings.md#filterable-attributes)** | List of attributes that can be used for filtering | `null` |
10+
| **[faceting](/learn/advanced/filtering_and_faceted_search.md)** | Faceting settings | `{}`
1011
| **[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) |
1112
| **[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 | |
1213
| **[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
9596

9697
<CodeSamples id="faceted_search_update_settings_1" />
9798

99+
## Faceting
100+
101+
The faceting settings of an index. Facets are specific use-cases of filters that can be used to refine search results.
102+
103+
::: tip
104+
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.
105+
:::
106+
107+
[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md)
108+
109+
#### Example
110+
111+
The following code sample will return a maximum of `5` facet values for each facet in the `movies` index:
112+
113+
<CodeSamples id="settings_guide_faceting_1" />
114+
98115
## Ranking rules
99116

100117
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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ You can customize the following index settings:
5858
- [Stop words](#stop-words)
5959
- [Displayed and searchable attributes](#displayed-and-searchable-attributes)
6060
- [Typo tolerance](#typo-tolerance)
61+
- [Faceting](#faceting)
6162

6263
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).
6364

@@ -129,3 +130,11 @@ Typo tolerance is a built-in feature that helps you find relevant results even w
129130
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).
130131

131132
[Learn more about typo tolerance](/learn/configuration/typo_tolerance.md)
133+
134+
### Faceting
135+
136+
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).
137+
138+
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).
139+
140+
[Learn more about faceting](/learn/advanced/filtering_and_faceted_search.md)

‎reference/api/faceting.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Faceting
2+
3+
_Child route of the [settings route](/reference/api/settings.md)._
4+
5+
This route allows you to configure the faceting settings for an index.
6+
7+
Faceting settings can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings.
8+
9+
To learn more about filtering and faceting, refer to our [dedicated guide](/learn/advanced/filtering_and_faceted_search.md).
10+
11+
::: warning
12+
Updating the settings means overwriting the default settings of Meilisearch. You can reset to default values using the `DELETE` routes.
13+
:::
14+
15+
## Get faceting settings
16+
17+
<RouteHighlighter method="GET" route="/indexes/{index_uid}/settings/faceting"/>
18+
19+
Get the faceting settings of an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
20+
21+
### Example
22+
23+
<CodeSamples id="get_faceting_settings_1" />
24+
25+
#### Response: `200 OK`
26+
27+
```json
28+
{
29+
"maxValuesPerFacet": 100
30+
}
31+
```
32+
33+
### Returned fields
34+
35+
#### `maxValuesPerFacet`
36+
37+
Maximum number of facet values returned for each facet.
38+
39+
## Update faceting settings
40+
41+
<RouteHighlighter method="PATCH" route="/indexes/{index_uid}/settings/faceting"/>
42+
43+
Partially update the faceting settings for an index. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
44+
45+
### Body
46+
47+
#### `maxValuesPerFacet`
48+
49+
**Type:** integer
50+
**Default value:** `100`
51+
52+
Configure the maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order.
53+
54+
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.
55+
56+
::: note
57+
Setting `maxValuesPerFacet` to a high value might negatively impact performance.
58+
:::
59+
60+
#### Example
61+
62+
<CodeSamples id="update_faceting_settings_1" />
63+
64+
#### Response: `202 Accepted`
65+
66+
```json
67+
{
68+
"taskUid": 1,
69+
"indexUid": "books",
70+
"status": "enqueued",
71+
"type": "settingsUpdate",
72+
"enqueuedAt": "2022-04-14T20:56:44.991039Z"
73+
}
74+
```
75+
76+
You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).
77+
78+
## Reset faceting settings
79+
80+
Reset an index's faceting settings to their default value. The index [`uid`](/learn/core_concepts/indexes.md#index-uid) is required.
81+
82+
#### Example
83+
84+
<CodeSamples id="reset_faceting_settings_1" />
85+
86+
#### Response: `200 OK`
87+
88+
```json
89+
{
90+
"taskUid": 1,
91+
"indexUid": "books",
92+
"status": "enqueued",
93+
"type": "settingsUpdate",
94+
"enqueuedAt": "2022-04-14T20:53:32.863107Z"
95+
}
96+
```
97+
98+
You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-task).

0 commit comments

Comments
 (0)