---
title: ES|QL MATCH_PHRASE function
description: 
url: https://www.elastic.co/elastic/docs-builder/docs/3958/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/elastic/docs-builder/docs/3958/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](/elastic/docs-builder/docs/3958/reference/query-languages/esql/esql-syntax#esql-function-named-params). See [`match_phrase`](https://www.elastic.co/elastic/docs-builder/docs/3958/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/elastic/docs-builder/docs/3958/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/elastic/docs-builder/docs/3958/reference/elasticsearch/mapping-reference/text) and keyword fields.
MatchPhrase is not supported for other field types, like [semantic_text](https://www.elastic.co/elastic/docs-builder/docs/3958/reference/elasticsearch/mapping-reference/semantic-text), boolean, date, or numeric types.
MatchPhrase can use [function named parameters](/elastic/docs-builder/docs/3958/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/elastic/docs-builder/docs/3958/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: Preview</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.
On a `keyword` expression the whole query string must equal a value exactly, matching
the term query semantics of `match_phrase` on an indexed keyword field.
When using `METADATA _score`, `MATCH_PHRASE` on an expression contributes to the relevance
score: a matching row scores the `boost` option (1.0 by default). Unlike indexed fields,
expressions are not scored with BM25, as there are no index statistics for an expression.
When searching `text` expressions, [function named parameters](/elastic/docs-builder/docs/3958/reference/query-languages/esql/esql-syntax#esql-function-named-params)
(match_phrase query options) are supported. As on an indexed field, the `analyzer` option
applies to the query string only: how the expression's values are analyzed is declared where
the column is created, through `TO_TEXT`'s `analyzer` option, and the query analyzer defaults
to that values analyzer (`standard` when none is declared). Analyzer names 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. On `keyword` expressions options are
not supported.
<tip>
  Learn more about using [ES|QL for search use cases](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3958/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 |