> ## Documentation Index
> Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter expression reference

> The `filter` search parameter expects a filter expression. Filter expressions are made of attributes, values, and several operators.

export const NoticeTag = ({label}) => <span className="noticeTag noticeTag--{ label }">
    {label}
  </span>;

The `filter` search parameter expects a filter expression. Filter expressions are made of attributes, values, and several operators.

`filter` expects a **filter expression** containing one or more **conditions**. A filter expression can be written as a string, array, or mix of both.

## Data types

Filters accept numeric and string values. Empty fields or fields containing an empty array will be ignored.

Filters do not work with [`NaN`](https://en.wikipedia.org/wiki/NaN) and infinite values such as `inf` and `-inf` as they are [not supported by JSON](https://en.wikipedia.org/wiki/JSON#Data_types). It is possible to filter infinite and `NaN` values if you parse them as strings, except when handling [`_geo` fields](/capabilities/geo_search/getting_started#preparing-documents-for-location-based-search).

<Warning>
  For best results, enforce homogeneous typing across fields, especially when dealing with large numbers. Meilisearch does not enforce a specific schema when indexing data, but the filtering engine may coerce the type of `value`. This can lead to undefined behavior, such as when big floating-point numbers are coerced into integers.
</Warning>

## Conditions

Conditions are a filter's basic building blocks. They are written in the `attribute OPERATOR value` format, where:

* `attribute` is the attribute of the field you want to filter on
* `OPERATOR` can be `=`, `!=`, `>`, `>=`, `<`, `<=`, `TO`, `EXISTS`, `IN`, `NOT`, `AND`, or `OR`
* `value` is the value the `OPERATOR` should look for in the `attribute`

### Examples

A basic condition requesting movies whose `genres` attribute is equal to `horror`:

<CodeGroup>
  ```
  genres = horror
  ```
</CodeGroup>

String values containing whitespace must be enclosed in single or double quotes:

<CodeGroup>
  ```
  director = 'Jordan Peele'
  director = "Tim Burton"
  ```
</CodeGroup>

## Filter operators

### Equality (`=`)

The equality operator (`=`) returns all documents containing a specific value for a given attribute:

<CodeGroup>
  ```
  genres = action
  ```
</CodeGroup>

When operating on strings, `=` is case-insensitive.

When the filtered attribute contains an array, `=` matches any document where at least one element in the array equals the specified value. For example, if a document has `"genres": ["action", "adventure"]`, the filter `genres = action` will match that document because `"action"` is one of the array's elements. The same logic applies to `!=`, `IN`, and other comparison operators.

The equality operator does not return any results for `null` and empty arrays.

### Inequality (`!=`)

The inequality operator (`!=`) returns all documents not selected by the equality operator. When operating on strings, `!=` is case-insensitive.

The following expression returns all movies without the `action` genre:

<CodeGroup>
  ```
  genres != action
  ```
</CodeGroup>

### Comparison (`>`, `<`, `>=`, `<=`)

The comparison operators (`>`, `<`, `>=`, `<=`) select documents satisfying a comparison. Comparison operators apply to both numerical and string values.

The expression below returns all documents with a user rating above 85:

<CodeGroup>
  ```
  rating.users > 85
  ```
</CodeGroup>

String comparisons resolve in lexicographic order: symbols followed by numbers followed by letters in alphabetic order. The expression below returns all documents released after the first day of 2004:

<CodeGroup>
  ```
  release_date > 2004-01-01
  ```
</CodeGroup>

### `TO`

`TO` is equivalent to `>= AND <=`. The following expression returns all documents with a rating of 80 or above but below 90:

<CodeGroup>
  ```
  rating.users 80 TO 89
  ```
</CodeGroup>

### `EXISTS`

The `EXISTS` operator checks for the existence of a field. Fields with empty or `null` values count as existing.

The following expression returns all documents containing the `release_date` field:

<CodeGroup>
  ```
  release_date EXISTS
  ```
</CodeGroup>

The negated form of the above expression can be written in two equivalent ways:

<CodeGroup>
  ```
  release_date NOT EXISTS
  NOT release_date EXISTS
  ```
</CodeGroup>

#### Vector filters

When using AI-powered search, you may also use `EXISTS` to filter documents containing vector data:

* `_vectors EXISTS`: matches all documents with an embedding
* `_vectors.{embedder_name} EXISTS`: matches all documents with an embedding for the given embedder
* `_vectors.{embedder_name}.userProvided EXISTS`: matches all documents with a user-provided embedding on the given embedder
* `_vectors.{embedder_name}.documentTemplate EXISTS`: matches all documents with an embedding generated from a document template. Excludes user-provided embeddings
* `_vectors.{embedder_name}.regenerate EXISTS`: matches all documents with an embedding scheduled for regeneration
* `_vectors.{embedder_name}.fragments.{fragment_name} EXISTS`: matches all documents with an embedding generated from the given multimodal fragment. Excludes user-provided embeddings

`_vectors` is only compatible with the `EXISTS` operator.

### `IS EMPTY`

The `IS EMPTY` operator selects documents in which the specified attribute exists but contains empty values. The following expression only returns documents with an empty `overview` field:

<CodeGroup>
  ```
  overview IS EMPTY
  ```
</CodeGroup>

`IS EMPTY` matches the following JSON values:

* `""`
* `[]`
* `{}`

Meilisearch does not treat `null` values as empty. To match `null` fields, use the [`IS NULL`](#is-null) operator.

Use `NOT` to build the negated form of `IS EMPTY`:

<CodeGroup>
  ```
  overview IS NOT EMPTY
  NOT overview IS EMPTY
  ```
</CodeGroup>

### `IS NULL`

The `IS NULL` operator selects documents in which the specified attribute exists but contains a `null` value. The following expression only returns documents with a `null` `overview` field:

<CodeGroup>
  ```
  overview IS NULL
  ```
</CodeGroup>

Use `NOT` to build the negated form of `IS NULL`:

<CodeGroup>
  ```
  overview IS NOT NULL
  NOT overview IS NULL
  ```
</CodeGroup>

### `IN`

`IN` combines equality operators by taking an array of comma-separated values delimited by square brackets. It selects all documents whose chosen field contains at least one of the specified values.

The following expression returns all documents whose `genres` includes either `horror`, `comedy`, or both:

<CodeGroup>
  ```
  genres IN [horror, comedy]
  genres = horror OR genres = comedy
  ```
</CodeGroup>

The negated form of the above expression can be written as:

<CodeGroup>
  ```
  genres NOT IN [horror, comedy]
  NOT genres IN [horror, comedy]
  ```
</CodeGroup>

### `CONTAINS`

<NoticeTag type="experimental" label="experimental" />

`CONTAINS` filters results containing partial matches to the specified string pattern, similar to a [SQL `LIKE`](https://dev.mysql.com/doc/refman/8.4/en/string-comparison-functions.html#operator_like).

The following expression returns all dairy products whose names contain `"kef"`:

<CodeGroup>
  ```
  dairy_products.name CONTAINS kef
  ```
</CodeGroup>

The negated form of the above expression can be written as:

<CodeGroup>
  ```
  dairy_products.name NOT CONTAINS kef
  NOT dairy_product.name CONTAINS kef
  ```
</CodeGroup>

<Note>
  This is an experimental feature. Use the experimental features endpoint to activate it:

  <CodeGroup>
    ```bash cURL theme={null}
    curl \
      -X PATCH 'MEILISEARCH_URL/experimental-features/' \
      -H 'Content-Type: application/json' \
      --data-binary '{
        "containsFilter": true
      }'
    ```
  </CodeGroup>
</Note>

### `STARTS WITH`

`STARTS WITH` filters results whose values start with the specified string pattern.

The following expression returns all dairy products whose name start with `"kef"`:

<CodeGroup>
  ```
  dairy_products.name STARTS WITH kef
  ```
</CodeGroup>

The negated form of the above expression can be written as:

<CodeGroup>
  ```
  dairy_products.name NOT STARTS WITH kef
  NOT dairy_product.name STARTS WITH kef
  ```
</CodeGroup>

### `NOT`

The negation operator (`NOT`) selects all documents that do not satisfy a condition. It has higher precedence than `AND` and `OR`.

The following expression will return all documents whose `genres` does not contain `horror` and documents with a missing `genres` field:

<CodeGroup>
  ```
  NOT genres = horror
  ```
</CodeGroup>

### `_foreign()`

Filter documents by properties of related documents in other indices using foreign filters. This requires a join relationship to be configured between indices.

The `_foreign()` function takes two arguments:

* `fieldName`: The join field name (the foreign key reference)
* `condition`: A filter condition to apply on the related document

The following expression returns all deals linked to a specific company:

<CodeGroup>
  ```
  _foreign(company, id = "company_42")
  ```
</CodeGroup>

<Warning>
  Foreign filters return an error when the filter on the related index matches more than 100 documents. Keep `_foreign()` conditions narrow, and prefer filtering on identifiers or tightly scoped attributes. See [Foreign filters](/capabilities/filtering_sorting_faceting/advanced/filtering_by_joined_data#hard-limit-foreign-filters-with-maximum-100-matching-documents) for details.
</Warning>

For more examples and use cases, see the [Foreign filters guide](/capabilities/filtering_sorting_faceting/advanced/filtering_by_joined_data).

## Filter expressions

You can build filter expressions by grouping basic conditions using `AND` and `OR`. Filter expressions can be written as strings, arrays, or a mix of both.

### Filter expression grouping operators

#### `AND`

`AND` connects two conditions and only returns documents that satisfy both of them. `AND` has higher precedence than `OR`.

The following expression returns all documents matching both conditions:

<CodeGroup>
  ```
  genres = horror AND director = 'Jordan Peele'
  ```
</CodeGroup>

#### `OR`

`OR` connects two conditions and returns results that satisfy at least one of them.

The following expression returns documents matching either condition:

<CodeGroup>
  ```
  genres = horror OR genres = comedy
  ```
</CodeGroup>

### Creating filter expressions with string operators and parentheses

Meilisearch reads string expressions from left to right. You can use parentheses to ensure expressions are correctly parsed.

For instance, if you want your results to only include `comedy` and `horror` documents released after March 1995, the parentheses in the following query are mandatory:

<CodeGroup>
  ```
  (genres = horror OR genres = comedy) AND release_date > 795484800
  ```
</CodeGroup>

Failing to add these parentheses will cause the same query to be parsed as:

<CodeGroup>
  ```
  genres = horror OR (genres = comedy AND release_date > 795484800)
  ```
</CodeGroup>

Translated into English, the above expression will only return comedies released after March 1995 or horror movies regardless of their `release_date`.

<Note>
  When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" OR title = "AND"`.
</Note>

### Creating filter expressions with arrays

Array expressions establish logical connectives by nesting arrays of strings. **Array filters can have a maximum depth of two.** Expressions with three or more levels of nesting will throw an error.

Outer array elements are connected by an `AND` operator. The following expression returns `horror` movies directed by `Jordan Peele`:

<CodeGroup>
  ```
  ["genres = horror", "director = 'Jordan Peele'"]
  ```
</CodeGroup>

Inner array elements are connected by an `OR` operator. The following expression returns either `horror` or `comedy` films:

<CodeGroup>
  ```
  [["genres = horror", "genres = comedy"]]
  ```
</CodeGroup>

Inner and outer arrays can be freely combined. The following expression returns both `horror` and `comedy` movies directed by `Jordan Peele`:

<CodeGroup>
  ```
  [["genres = horror", "genres = comedy"], "director = 'Jordan Peele'"]
  ```
</CodeGroup>

### Combining arrays and string operators

You can also create filter expressions that use both array and string syntax.

The following filter is written as a string and only returns movies not directed by `Jordan Peele` that belong to the `comedy` or `horror` genres:

<CodeGroup>
  ```
  "(genres = comedy OR genres = horror) AND director != 'Jordan Peele'"
  ```
</CodeGroup>

You can write the same filter mixing arrays and strings:

<CodeGroup>
  ```
  [["genres = comedy", "genres = horror"], "NOT director = 'Jordan Peele'"]
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Get started with filtering and sorting" href="/capabilities/filtering_sorting_faceting/getting_started">
    Configure filterable and sortable attributes for your index.
  </Card>

  <Card title="Filter with facets" href="/capabilities/filtering_sorting_faceting/how_to/filter_with_facets">
    Build faceted navigation to let users refine search results interactively.
  </Card>

  <Card title="Get started with geo search" href="/capabilities/geo_search/getting_started">
    Filter and sort results based on geographic location.
  </Card>
</CardGroup>