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

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


## Syntax

![Embedded](https://www.elastic.co/elastic/docs-builder/docs/2824/reference/query-languages/esql/images/functions/match_phrase.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) MatchPhrase additional options as [function named parameters](/elastic/docs-builder/docs/2824/reference/query-languages/esql/esql-syntax#esql-function-named-params). See [`match_phrase`](https://www.elastic.co/elastic/docs-builder/docs/2824/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/2824/reference/query-languages/query-dsl/query-dsl-match-query-phrase) on the specified field. 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/2824/reference/elasticsearch/mapping-reference/text) fields, as well as other field types like keyword, boolean, or date types.
MatchPhrase is not supported for [semantic_text](https://www.elastic.co/elastic/docs-builder/docs/2824/reference/elasticsearch/mapping-reference/semantic-text) or numeric types.
MatchPhrase can use [function named parameters](/elastic/docs-builder/docs/2824/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/2824/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.

## Supported types


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


### Supported function named parameters

<definitions>
  <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>
  <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>
</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 |