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

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

Performs a match_phrase query on the specified field or expression.

## Syntax

![Embedded](https://www.elastic.co/docs/reference/query-languages/esql/images/generated/x-pack-esql/functions/match_phrase.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) MatchPhrase additional options as [function named parameters](/docs/reference/query-languages/esql/esql-syntax#esql-function-named-params). See [`match_phrase`](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-match-query-phrase) for more information.
  </definition>
</definitions>


## Description

Use `MATCH_PHRASE` to perform a [`match_phrase`](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-match-query-phrase) on the specified field or expression. Using `MATCH_PHRASE` is equivalent to using the `match_phrase` query in the Elasticsearch Query DSL.
MatchPhrase can be used on [text](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/text) and keyword fields.
MatchPhrase is not supported for other field types, like [semantic_text](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/semantic-text), boolean, date, or numeric types.
MatchPhrase can use [function named parameters](/docs/reference/query-languages/esql/esql-syntax#esql-function-named-params) to specify additional options for the
match_phrase query.
All [`match_phrase`](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-match-query-phrase) query parameters are supported.
`MATCH_PHRASE` returns true if the provided query matches the row.
**`MATCH_PHRASE` on expressions**
<applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to>
`MATCH_PHRASE` can also search `text` and `keyword` 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.
Analyzers, options, and scoring work differently than on an indexed field.
To learn more, refer to [runtime search](https://www.elastic.co/docs/reference/query-languages/esql/esql-runtime-search).
<tip>
  Learn more about using [ES|QL for search use cases](https://docs-demo.elastic.dev/docs/solutions/search/esql-for-search).
</tip>


## Supported types


| field   | query   | options          | result  |
|---------|---------|------------------|---------|
| keyword | keyword | named parameters | boolean |
| text    | keyword | named parameters | boolean |


### Supported function named parameters

<definitions>
  <definition term="analyzer">
    (keyword) Analyzer used to convert the text in the query value into tokens. Defaults to the index-time analyzer mapped for the field; if no analyzer is mapped, the index’s default analyzer is used. For expressions not backed by an index, defaults to the values analyzer declared through `TO_TEXT` (`standard` when none is declared).
  </definition>
  <definition term="slop">
    (integer) Maximum number of positions allowed between matching tokens. Defaults to 0. Transposed terms have a slop of 2.
  </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>
  <definition term="boost">
    (float) Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0.
  </definition>
</definitions>


## Example

<applies-to>
  - Elastic Stack: Generally available since 9.1
</applies-to>

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


| book_no:keyword | author:text      |
|-----------------|------------------|
| 2713            | William Faulkner |
| 2883            | William Faulkner |
| 4724            | William Faulkner |
| 4977            | William Faulkner |
| 5119            | William Faulkner |