```yaml {applies_to}
serverless: ga
stack: ga
```

The `WHERE` processing command produces a table that contains all the rows from
the input table for which the provided condition evaluates to `true`.

::::{tip}
In case of value exclusions, fields with `null` values will be excluded from search results.
In this context a `null` means either there is an explicit `null` value in the document or
there is no value at all. For example: `WHERE field != "value"` will be interpreted as
`WHERE field != "value" AND field IS NOT NULL`.
::::


## Syntax

```esql
WHERE expression
```

## Parameters

`expression`
:   A boolean expression.

## Examples

The following examples show common ways to filter rows with `WHERE`.

### Filter rows by field value

:::{include} ../../generated/x-pack-esql/commands/examples/docs.csv-spec/where.md
:::

Which, if `still_hired` is a boolean field, can be simplified to:

:::{include} ../../generated/x-pack-esql/commands/examples/docs.csv-spec/whereBoolean.md
:::

### Filter by time range

Use date math to retrieve data from a specific time range. For example, to
retrieve the last hour of logs:

:::{include} ../../generated/x-pack-esql/commands/examples/date.csv-spec/docsNowWhere.md
:::

### Use WHERE with a function

`WHERE` supports various [functions](/reference/query-languages/esql/esql-functions-operators.md#esql-functions).
For example the [`LENGTH`](/reference/query-languages/esql/functions-operators/string-functions/length.md) function:

:::{include} ../../generated/x-pack-esql/commands/examples/docs.csv-spec/whereFunction.md
:::

For a complete list of all functions, refer to [Functions overview](/reference/query-languages/esql/esql-functions-operators.md#esql-functions).

### NULL Predicates

For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates.

:::{include} ../../generated/x-pack-esql/operators/examples/is_null.md
:::

:::{include} ../../generated/x-pack-esql/operators/examples/is_not_null.md
:::

### Matching text

Use [`MATCH`](/reference/query-languages/esql/functions-operators/search-functions/match.md) to perform a
[match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) on a specified field.
`MATCH` works on text fields as well as boolean, date, and numeric types.

:::{include} ../../generated/x-pack-esql/functions/examples/match.md
:::

::::{tip}
You can also use the shorthand [match operator](/reference/query-languages/esql/functions-operators/operators.md#esql-match-operator) `:` instead of `MATCH`.

::::

### LIKE and RLIKE

Use `LIKE` to filter data based on string patterns using wildcards. `LIKE` usually acts on a field placed on the left-hand side of the operator, but it can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern.

The following wildcard characters are supported:

* `*` matches zero or more characters.
* `?` matches one character.

:::{include} ../../generated/x-pack-esql/operators/types/like.md
:::

:::{include} ../../generated/x-pack-esql/operators/examples/like.md
:::

:::{include} ../../generated/x-pack-esql/operators/detailedDescription/like.md
:::

Use `RLIKE` to filter data based on string patterns using using [regular expressions](/reference/query-languages/query-dsl/regexp-syntax.md). `RLIKE` usually acts on a field placed on the left-hand side of the operator, but it can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern.

:::{include} ../../generated/x-pack-esql/operators/types/rlike.md
:::

:::{include} ../../generated/x-pack-esql/operators/examples/rlike.md
:::

:::{include} ../../generated/x-pack-esql/operators/detailedDescription/rlike.md
:::

### IN

The `IN` operator allows testing whether a field or expression equals an element
in a list of literals, fields or expressions:

:::{include} ../../generated/x-pack-esql/operators/examples/in.md
:::

For a complete list of all operators, refer to [Operators](/reference/query-languages/esql/esql-functions-operators.md#esql-operators-overview).
