---
title: ES|QL MATCH function
description: 
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/query-languages/esql/functions-operators/search-functions/match
products:
  - Elasticsearch
---

# ES|QL MATCH function
<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.1
  - Elastic Stack: Preview in 9.0
</applies-to>

Performs a match query on the specified field or expression.

## Syntax

![Embedded](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/query-languages/esql/images/generated/x-pack-esql/functions/match.svg)


## Parameters

<definitions>
  <definition term="field">
    Field or expression that the query will target.
  </definition>
  <definition term="query">
    Value to find in the provided field or expression.
  </definition>
  <definition term="options">
    (Optional) Match additional options as [function named parameters](/elastic/elasticsearch/pull/155690/reference/query-languages/esql/esql-syntax#esql-function-named-params).
  </definition>
</definitions>


## Description

Use `MATCH` to perform a [match query](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/query-languages/query-dsl/query-dsl-match-query) on the specified field or expression. Using `MATCH` is equivalent to using the `match` query in the Elasticsearch Query DSL.
Match can be used on fields from the text family like [text](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/elasticsearch/mapping-reference/text) and [semantic_text](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/elasticsearch/mapping-reference/semantic-text),
as well as other field types like keyword, boolean, dates, and numeric types.
When Match is used on a [semantic_text](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155690/reference/elasticsearch/mapping-reference/semantic-text) field, it will perform a semantic query on the field.
Match can use [function named parameters](/elastic/elasticsearch/pull/155690/reference/query-languages/esql/esql-syntax#esql-function-named-params) to specify additional options
for the match query.
All [match query parameters](/elastic/elasticsearch/pull/155690/reference/query-languages/query-dsl/query-dsl-match-query#match-field-params) are supported.
For a simplified syntax, you can use the [match operator](/elastic/elasticsearch/pull/155690/reference/query-languages/esql/functions-operators/operators#esql-match-operator) `:` operator instead of `MATCH`.
`MATCH` returns true if the provided query matches the row.
**`MATCH` on expressions**
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Preview</applies-to>
`MATCH` can also search expressions that are not backed by an index, such as
computed columns produced by `EVAL`, `STATS`, or other commands.
When the target is not an indexed field, the search evaluates by scanning
values row by row, which may be slower on large datasets.
Additionally, `MATCH` on an expression does not contribute to the relevance score
when using `METADATA _score`.
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Preview</applies-to>
When searching `text` expressions, [function named parameters](/elastic/elasticsearch/pull/155690/reference/query-languages/esql/esql-syntax#esql-function-named-params)
(match query options) are supported. The `analyzer` option must name a registered analyzer
(prebuilt or plugin-contributed). Per-index custom analyzers cannot be used because the
expression is not backed by an index. Unlike on an indexed field, the analyzer is applied to
both the query and the expression values. When no analyzer is specified, the `standard`
analyzer is used. On other expression types options are not supported.
<tip>
  Learn more about using [ES|QL for search use cases](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/solutions/search/esql-for-search).
</tip>


## Supported types


| field         | query         | options          | result  |
|---------------|---------------|------------------|---------|
| boolean       | boolean       | named parameters | boolean |
| boolean       | keyword       | named parameters | boolean |
| date          | date          | named parameters | boolean |
| date          | keyword       | named parameters | boolean |
| date_nanos    | date_nanos    | named parameters | boolean |
| date_nanos    | keyword       | named parameters | boolean |
| double        | double        | named parameters | boolean |
| double        | integer       | named parameters | boolean |
| double        | keyword       | named parameters | boolean |
| double        | long          | named parameters | boolean |
| integer       | double        | named parameters | boolean |
| integer       | integer       | named parameters | boolean |
| integer       | keyword       | named parameters | boolean |
| integer       | long          | named parameters | boolean |
| ip            | ip            | named parameters | boolean |
| ip            | keyword       | named parameters | boolean |
| keyword       | keyword       | named parameters | boolean |
| long          | double        | named parameters | boolean |
| long          | integer       | named parameters | boolean |
| long          | keyword       | named parameters | boolean |
| long          | long          | named parameters | boolean |
| text          | keyword       | named parameters | boolean |
| unsigned_long | double        | named parameters | boolean |
| unsigned_long | integer       | named parameters | boolean |
| unsigned_long | keyword       | named parameters | boolean |
| unsigned_long | long          | named parameters | boolean |
| unsigned_long | unsigned_long | named parameters | boolean |
| version       | keyword       | named parameters | boolean |
| version       | version       | named parameters | boolean |


### Supported function named parameters

<definitions>
  <definition term="analyzer">
    (keyword) Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the field. If no analyzer is mapped, the index’s default analyzer is used.
  </definition>
  <definition term="auto_generate_synonyms_phrase_query">
    (boolean) If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true.
  </definition>
  <definition term="fuzziness">
    (keyword) Maximum edit distance allowed for matching.
  </definition>
  <definition term="boost">
    (float) Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0.
  </definition>
  <definition term="fuzzy_transpositions">
    (boolean) If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true.
  </definition>
  <definition term="fuzzy_rewrite">
    (keyword) Method used to rewrite the query. See the rewrite parameter for valid values and more information. If the fuzziness parameter is not 0, the match query uses a fuzzy_rewrite method of top_terms_blended_freqs_${max_expansions} by default.
  </definition>
  <definition term="lenient">
    (boolean) If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false.
  </definition>
  <definition term="max_expansions">
    (integer) Maximum number of terms to which the query will expand. Defaults to 50.
  </definition>
  <definition term="minimum_should_match">
    (integer) Minimum number of clauses that must match for a document to be returned.
  </definition>
  <definition term="operator">
    (keyword) Boolean logic used to interpret text in the query value. Defaults to OR.
  </definition>
  <definition term="prefix_length">
    (integer) Number of beginning characters left unchanged for fuzzy matching. Defaults to 0.
  </definition>
  <definition term="zero_terms_query">
    (keyword) Indicates whether all documents or none are returned if the analyzer removes all tokens, such as when using a stop filter. Defaults to none.
  </definition>
</definitions>


## Examples

```esql
FROM books
| WHERE MATCH(author, "Faulkner")
```


| book_no:keyword | author:text                                        |
|-----------------|----------------------------------------------------|
| 2378            | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] |
| 2713            | William Faulkner                                   |
| 2847            | Colleen Faulkner                                   |
| 2883            | William Faulkner                                   |
| 3293            | Danny Faulkner                                     |

```esql
FROM books
| WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"})
| KEEP title;
```


| title:text                         |
|------------------------------------|
| The Hobbit or There and Back Again |