ES|QL MATCH function

Performs a match query on the specified field or expression.

field

Field or expression that the query will target.

query

Value to find in the provided field or expression.

options

(Optional) Match additional options as function named parameters.

Use MATCH to perform a match query on the specified field or expression. 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 and semantic_text, as well as other field types like keyword, boolean, dates, and numeric types. When Match is used on a semantic_text field, it will perform a semantic query on the field.

Match can use function named parameters to specify additional options for the match query. All match query parameters are supported.

For a simplified syntax, you can use the match operator : operator instead of MATCH.

MATCH returns true if the provided query matches the row.

MATCH on expressions

Stack Preview 9.5 … The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview in 9.5 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. MATCH can also search 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.

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).

auto_generate_synonyms_phrase_query

(boolean) If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true.

fuzziness

(keyword) Maximum edit distance allowed for matching.

boost

(float) Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0.

fuzzy_transpositions

(boolean) If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true.

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.

lenient

(boolean) If false, format-based errors, such as a text query value for a numeric field, are returned. If true, such values do not match. Defaults to true.

max_expansions

(integer) Maximum number of terms to which the query will expand. Defaults to 50.

minimum_should_match

(integer) Minimum number of clauses that must match for a document to be returned.

operator

(keyword) Boolean logic used to interpret text in the query value. Defaults to OR.

prefix_length

(integer) Number of beginning characters left unchanged for fuzzy matching. Defaults to 0.

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.

FROM books
| WHERE MATCH(author, "Faulkner")

FROM books
| WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"})
| KEEP title;