Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

v1.12: prefixSearch and facetSearch index settings #3070

Open
wants to merge 4 commits into
base: v1.12
Choose a base branch
from
Open

v1.12: prefixSearch and facetSearch index settings #3070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cd4c05f
add prefix and facet search opt-outs
guimachiavelli Dec 5, 2024
4758e8f
add DELETE routehighlighter component
guimachiavelli Dec 5, 2024
a39fb06
improve wording
guimachiavelli Dec 12, 2024
74788bf
use consistent index uid placeholder
guimachiavelli Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .code-samples.meilisearch.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1201,6 +1201,28 @@ update_proximity_precision_settings_1: |-
reset_proximity_precision_settings_1: |-
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision'
get_facet_search_settings_1: |-
curl \
-X GET 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search'
update_facet_search_settings_1: |-
curl \
-X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search' \
-H 'Content-Type: application/json' \
--data-binary 'false'
reset_facet_search_settings_1: |-
curl \
-X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/facet-search'
get_prefix_search_settings_1: |-
curl \
-X GET 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search'
update_prefix_search_settings_1: |-
curl \
-X PUT 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search' \
-H 'Content-Type: application/json' \
--data-binary '"disabled"'
reset_prefix_search_settings_1: |-
curl \
-X DELETE 'http://localhost:7700/indexes/INDEX_UID/settings/prefix-search'
index_settings_tutorial_api_get_setting_1: |-
curl \
-X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/searchable-attributes'
Expand Down
203 changes: 203 additions & 0 deletions reference/api/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ By default, the settings object looks like this. All fields are modifiable.
"maxTotalHits": 1000
},
"proximityPrecision": "byWord",
"facetSearch": true,
"prefixSearch": "indexingTime",
"searchCutoffMs": null
}
```
Expand Down Expand Up @@ -126,6 +128,8 @@ Get the settings of an index.
"maxTotalHits": 1000
},
"proximityPrecision": "byWord",
"facetSearch": true,
"prefixSearch": "indexingTime",
"searchCutoffMs": null
}
```
Expand Down Expand Up @@ -159,6 +163,8 @@ If the provided index does not exist, it will be created.
| **[`filterableAttributes`](#filterable-attributes)** | Array of strings | Empty | Attributes to use as filters and facets |
| **[`pagination`](#pagination)** | Object | [Default object](#pagination-object) | Pagination settings |
| **[`proximityPrecision`](#proximity-precision)** | String | `"byWord"` | Precision level when calculating the proximity ranking rule |
| **[`facetSearch`](#facet-search)** | Boolean | `true` | Enable or disable [facet search](/reference/api/facet_search) functionality |
| **[`prefixSearch`](#prefix-search)** | String | `"indexingTime"` | When Meilisearch should return results only matching the beginning of query |
| **[`rankingRules`](#ranking-rules)** | Array of strings | `["words",`<br />`"typo",`<br />`"proximity",`<br />`"attribute",`<br />`"sort",`<br />`"exactness"]` | List of ranking rules in order of importance |
| **[`searchableAttributes`](#searchable-attributes)** | Array of strings | All attributes: `["*"]` | Fields in which to search for matching query words sorted by order of importance |
| **[`searchCutoffMs`](#search-cutoff)** | Integer | `null`, or 1500ms | Maximum duration of a search query |
Expand Down Expand Up @@ -1115,6 +1121,8 @@ You can use the returned `taskUid` to get more details on [the status of the tas

### Reset proximity precision settings

<RouteHighlighter method="DELETE" route="/indexes/{index_uid}/settings/proximity-precision"/>

Reset an index's proximity precision setting to its default value.

#### Path parameters
Expand All @@ -1141,6 +1149,201 @@ Reset an index's proximity precision setting to its default value.

You can use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).

## Facet search

Processing filterable attributes for facet search is a resource-intensive operation. This feature is enabled by default, but disabling it may speed up indexing.

`facetSearch` accepts a single Boolean value. If set to `false`, it disables facet search for the whole index. Meilisearch returns an error if you try to access the `/facet-search` endpoint when facet search is disabled.

### Get facet search settings

<RouteHighlighter method="GET" route="/indexes/{index_uid}/settings/facet-search"/>

Get the facet search settings of an index.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Example

<CodeSamples id="get_facet_search_settings_1" />

##### Response: `200 OK`

```json
{
"facetSearch": true
}
```

### Update facet search settings

<RouteHighlighter method="PUT" route="/indexes/{index_uid}/settings/facet-search"/>

Update the facet search settings for an index.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Body

```
<Boolean>
```

#### Example

<CodeSamples id="update_facet_search_settings_1" />

##### Response: `202 Accepted`

```json
{
"taskUid": 1,
"indexUid": "INDEX_UID",
"status": "enqueued",
"type": "settingsUpdate",
"enqueuedAt": "2024-07-19T22:33:18.523881Z"
}
```

Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).

### Reset facet search settings

<RouteHighlighter method="DELETE" route="/indexes/{index_uid}/settings/facet-search"/>

Reset an index's facet search to its default settings.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Example

<CodeSamples id="reset_facet_search_settings_1" />

##### Response: `202 Accepted`

```json
{
"taskUid": 1,
"indexUid": "INDEX_UID",
"status": "enqueued",
"type": "settingsUpdate",
"enqueuedAt": "2024-07-19T22:35:33.723983Z"
}
```

Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).

## Prefix search

Prefix search is the process through which Meilisearch matches documents that begin with a specific query term, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default.

Use `prefixSearch` to change how prefix search works. It accepts one of the following strings:

- `"indexingTime"`: calculate prefix search during indexing. This is the default behavior
- `"disabled"`: do not calculate prefix search. May speed up indexing, but will severely impact search result relevancy

### Get prefix search settings

<RouteHighlighter method="GET" route="/indexes/{index_uid}/settings/prefix-search"/>

Get the prefix search settings of an index.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Example

<CodeSamples id="get_prefix_search_settings_1" />

##### Response: `200 OK`

```json
{
"prefixSearch": "indexingTime"
}
```

### Update prefix search settings

<RouteHighlighter method="PUT" route="/indexes/{index_uid}/settings/prefix-search"/>

Update the prefix search settings for an index.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Body

```
"indexingTime" | "disabled"
```

#### Example

<CodeSamples id="update_prefix_search_settings_1" />

##### Response: `202 Accepted`

```json
{
"taskUid": 1,
"indexUid": "INDEX_UID",
"status": "enqueued",
"type": "settingsUpdate",
"enqueuedAt": "2024-07-19T22:33:18.523881Z"
}
```

Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).

### Reset prefix search settings

<RouteHighlighter method="DELETE" route="/indexes/{index_uid}/settings/prefix-search"/>

Reset an index's prefix search to its default settings.

#### Path parameters

| Name | Type | Description |
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

#### Example

<CodeSamples id="reset_facet_search_settings_1" />

##### Response: `202 Accepted`

```json
{
"taskUid": 1,
"indexUid": "INDEX_UID",
"status": "enqueued",
"type": "settingsUpdate",
"enqueuedAt": "2024-07-19T22:35:33.723983Z"
}
```

Use the returned `taskUid` to get more details on [the status of the task](/reference/api/tasks#get-one-task).

## Ranking rules

Ranking rules are built-in rules that rank search results according to certain criteria. They are applied in the same order in which they appear in the `rankingRules` array.
Expand Down
14 changes: 13 additions & 1 deletion reference/errors/error_codes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ The requested document can't be retrieved. Either it doesn't exist, or the datab

An error occurred during the dump creation process. The task was aborted.

## `facet_search_disabled`

The [`/facet-search`](/reference/api/facet_search) route has been queried while [the `facetSearch` index setting](/reference/api/settings#facet-search) is set to `false`.

## `immutable_api_key_actions`

The [`actions`](/reference/api/keys#actions) field of an API key cannot be modified.
Expand Down Expand Up @@ -93,7 +97,7 @@ The requested index already has a primary key that [cannot be changed](/learn/ge

## `internal`

Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary.
Meilisearch experienced an internal error. Check the error message, and [open an issue](https://github.com/meilisearch/meilisearch/issues/new?assignees=&labels=&template=bug_report&title=) if necessary.

## `invalid_api_key`

Expand Down Expand Up @@ -296,6 +300,10 @@ The [`limit`](/reference/api/search#limit) parameter is invalid. It should be an

The [`locales`](/reference/api/search#query-locales) parameter is invalid.

## `invalid_settings_facet_search`

The [`facetSearch`](/reference/api/settings#facet-search) index setting value is invalid.

## `invalid_settings_localized_attributes`

The [`localizedAttributes`](/reference/api/settings#localized-attributes) index setting value is invalid.
Expand All @@ -308,6 +316,10 @@ The [`matchingStrategy`](/reference/api/search#matching-strategy) parameter is i

The [`offset`](/reference/api/search#offset) parameter is invalid. It should be an integer.

## `invalid_settings_prefix_search`

The [`prefixSearch`](/reference/api/settings#prefix-search) index setting value is invalid.

## `invalid_search_page`

The [`page`](/reference/api/search#page) parameter is invalid. It should be an integer.
Expand Down
Loading