---
title: ES|QL MATCH_PHRASE function
description: 
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/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://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/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/elasticsearch/pull/155697/reference/query-languages/esql/esql-syntax#esql-function-named-params). See [`match_phrase`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/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://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/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://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/reference/elasticsearch/mapping-reference/text) and keyword fields.
MatchPhrase is not supported for other field types, like [semantic_text](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/reference/elasticsearch/mapping-reference/semantic-text), boolean, date, or numeric types.
MatchPhrase can use [function named parameters](/elastic/elasticsearch/pull/155697/reference/query-languages/esql/esql-syntax#esql-function-named-params) to specify additional options for the
match_phrase query.
All [`match_phrase`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/155697/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.
Additionally, `MATCH_PHRASE` on an expression does not contribute to the relevance score
when using `METADATA _score`.
When searching `text` expressions, [function named parameters](/elastic/elasticsearch/pull/155697/reference/query-languages/esql/esql-syntax#esql-function-named-params)
(match_phrase 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 `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-content/tree/main/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 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="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 |