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.14: New filterableAttributes format #3207

Open
wants to merge 3 commits into
base: v1.14
Choose a base branch
from
Open

v1.14: New filterableAttributes format #3207

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e039fe3
add new `filterableAttributes` settings format
guimachiavelli Mar 27, 2025
3975cd1
Apply suggestions from code review
guimachiavelli Apr 3, 2025
151e453
address reviewer feedback
guimachiavelli Apr 3, 2025
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
65 changes: 54 additions & 11 deletions reference/api/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ If the provided index does not exist, it will be created.
| **[`displayedAttributes`](#displayed-attributes)** | Array of strings | All attributes: `["*"]` | Fields displayed in the returned documents |
| **[`distinctAttribute`](#distinct-attribute)** | String | `null` | Search returns documents with distinct (different) values of the given field |
| **[`faceting`](#faceting)** | Object | [Default object](#faceting-object) | Faceting settings |
| **[`filterableAttributes`](#filterable-attributes)** | Array of strings | Empty | Attributes to use as filters and facets |
| **[`filterableAttributes`](#filterable-attributes)** | Array of strings or array of objects | 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 |
Expand Down Expand Up @@ -684,13 +684,43 @@ You can use the returned `taskUid` to get more details on [the status of the tas

## Filterable attributes

Attributes in the `filterableAttributes` list can be used as filters or facets.
Attributes in the `filterableAttributes` list can be used as [filters](/learn/filtering_and_sorting/filter_search_results) or [facets](/learn/filtering_and_sorting/search_with_facet_filters).

<Capsule intent="warning">
Updating filterable attributes will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
Updating filterable attributes will re-index all documents in the index, which can take some time. To reduce RAM consumption, first update your index settings and then add documents.
</Capsule>

[To learn more about filterable attributes, refer to our dedicated guide.](/learn/filtering_and_sorting/filter_search_results)
### Filterable attribute object

`filterableAttributes` may be either an array of strings or an array of filterable attribute objects.

Filterable attribute objects must contain the following fields:

| Name | Type | Default value | Description |
| ----------------------- | ---------------- | ------------- | -------------------------------------------------------- |
| **`attributePatterns`** | Array of strings | `[]` | A list of strings indicating filterable fields |
| **`features`** | Object | `{}` | A list outlining filter types enabled for the specified attributes |

#### `attributePatterns`

Attribute patterns may begin or end with a * wildcard to match multiple fields: `customer_*`, `attribute*`.

#### `features`

`features` allows you to decide which filter features are allowed for the specified attributes. It accepts the following fields:

- `facetSearch`: Whether facet search should be enabled for the specified attributes. Boolean, defaults to `false`
- `filter`: A list outlining the filter types for the specified attributes. Must be an object and accepts the following fields:
- `equality`: Enables `=`, `!=`, `IN`, `EXISTS`, `IS NULL`, `IS EMPTY`, `NOT`, `AND`, and `OR`. Boolean, defaults to `true`
- `comparison`: Enables `>`, `>=`, `<`, `<=`, `TO`, `EXISTS`, `IS NULL`, `IS EMPTY`, `NOT`, `AND`, and `OR`. Boolean, defaults to `false`

Calculating `comparison` filters is a resource-intensive operation. Disabling them may lead to better search and indexing performance. `equality` filters use fewer resources and have limited impact on performance.

<Capsule intent="warning" title="_geo field">
Use the simple string syntax to match the reserved attribute `_geo`.

If set as a filterable attribute, `_geo` ignores the `features` field and automatically activates all search features. `_geo` also will not be matched by wildcard `attributePatterns` such as `_*`.
</Capsule>

### Get filterable attributes

Expand Down Expand Up @@ -736,15 +766,28 @@ Update an index's filterable attributes list.
[<String>, <String>, …]
```

An array of strings containing the attributes that can be used as filters at query time.
An array of strings containing the attributes that can be used as filters at query time. All filter types are enabled for the specified attributes when using the array of strings format.

If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: `"filterableAttributes": ["release_date.year"]`.
You may also use an array of objects:

<Capsule intent="warning">
If the field does not exist, no error will be thrown.
</Capsule>
```
[
{
"attributePatterns": [<String>, <String>, …],
"features": {
"facetSearch": <Boolean>,
"filter": {
"equality": <Boolean>,
"comparison": <Boolean>
}
}
}
]
```

If the specified field does not exist, Meilisearch will silently ignore it.

[To learn more about filterable attributes, refer to our dedicated guide.](/learn/filtering_and_sorting/filter_search_results)
If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: `"filterableAttributes": ["release_date.year"]` or `"attributePatterns": ["release_date.year"]`.

#### Example

Expand Down Expand Up @@ -821,7 +864,7 @@ Locale objects must have the following fields:
| Name | Type | Default value | Description |
| :----------------- | :------ | :------------ | :---------------------------------------------------------- |
| **`locales`** | Array of strings | `[]` | A list of strings indicating one or more ISO-639 locales |
| **`attribute_patterns`** | Array of strings | `[]` | A list of strings indicating which fields correspond to the specified locales |
| **`attributePatterns`** | Array of strings | `[]` | A list of strings indicating which fields correspond to the specified locales |

#### `locales`

Expand Down