---
title: ES|QL MATCH function
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/functions-operators/search-functions/match
products:
  - Elasticsearch
---

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


## Syntax

![Embedded](https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/esql/images/functions/match.svg)


## Parameters

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


## Description

Use `MATCH` to perform a [match query](https://www.elastic.co/elastic/docs-builder/docs/3028/reference/query-languages/query-dsl/query-dsl-match-query) on the specified field. 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://www.elastic.co/elastic/docs-builder/docs/3028/reference/elasticsearch/mapping-reference/text) and [semantic_text](https://www.elastic.co/elastic/docs-builder/docs/3028/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://www.elastic.co/elastic/docs-builder/docs/3028/reference/elasticsearch/mapping-reference/semantic-text) field, it will perform a semantic query on the field.
Match can use [function named parameters](/elastic/docs-builder/docs/3028/reference/query-languages/esql/esql-syntax#esql-function-named-params) to specify additional options
for the match query.
All [match query parameters](/elastic/docs-builder/docs/3028/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/docs-builder/docs/3028/reference/query-languages/esql/functions-operators/operators#esql-match-operator) `:` operator instead of `MATCH`.
`MATCH` returns true if the provided query matches the row.

## 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 |