« ES|QL REST API Using ES|QL in Kibana »
Elastic Docs ›Elasticsearch Guide [8.19] ›ES|QL ›Using ES|QL

Using ES|QL for search

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Using ES|QL for search

edit

This page provides an overview of how to use ES|QL for search use cases.

For a hands-on tutorial check out Tutorial: Search and filter with ES|QL.

ES|QL search quick reference

edit

The following table summarizes the key search features available in ES|QL and when they were introduced, organized chronologically by release.

Feature Description Available since

Match function/operator

Perform basic text searches with MATCH function or match operator (:)

8.17

Query string function

Execute complex queries with QSTR using Query String syntax

8.17

Relevance scoring

Calculate and sort by relevance with METADATA _score

8.18/9.0

Semantic search

Perform semantic searches on semantic_text field types

8.18/9.0

Hybrid search

Combine lexical and semantic search approaches with custom weights

8.18/9.0

Kibana Query Language

Use Kibana Query Language with the KQL function

8.18/9.0

Match phrase function

Perform phrase matching with MATCH_PHRASE function

8.19/9.1

How search works in ES|QL

edit

ES|QL provides two distinct approaches for finding documents: filtering and searching. Understanding the difference is crucial for building effective queries and choosing the right approach for your use case.

Filtering removes documents that don’t meet your criteria. It’s a binary yes/no decision - documents either match your conditions or they don’t. Filtering is faster because it doesn’t calculate relevance scores and leverages efficient index structures for exact matches, ranges, and boolean logic.

Searching both filters documents and ranks them by relevance. It calculates a score for each matching document based on how well the content matches your query, allowing you to sort results from most relevant to least relevant. Search functions use advanced text analysis including stemming, synonyms, and fuzzy matching.

When to choose filtering:

  • Exact category matches (category.keyword == "Electronics")
  • Date ranges (date >= "2023-01-01")
  • Numerical comparisons (price < 100)
  • Any scenario where you want all matching results without ranking

When to choose searching:

  • Text queries where some results are more relevant than others
  • Finding documents similar to a search phrase
  • Any scenario where you want the "best" matches first
  • You want to use analyzers or synonyms

ES|QL’s search functions address several key limitations that existed for text filtering: they work directly on multivalued fields, leverage analyzers for proper text analysis, and use optimized Lucene index structures for better performance.

Relevance scoring

edit

To get relevance-ranked results, you must explicitly request scoring with METADATA _score and sort by the score. Without this, even search functions like MATCH will only filter documents without ranking them.

Without METADATA _score: All operations are filtering-only, even MATCH, QSTR, and KQL functions. Documents either match or don’t match - no ranking occurs.

With METADATA _score: Search functions contribute to relevance scores, while filtering operations (range conditions, exact matches) don’t affect scoring. You must explicitly use SORT _score DESC to see the most relevant results first.

This gives you full control over when to use fast filtering versus slower but more powerful relevance-based searching.

Search functions

edit

The following functions provide text-based search capabilities in ES|QL with different levels of precision and control.

MATCH function and operator

edit

ES|QL offers two syntax options for match, which replicate the functionality of match queries in Query DSL.

  • Use the compact match operator (:) for simple text matching with default parameters.
  • Use the MATCH function syntax for more control over the query, such as specifying analyzers, fuzziness, and other parameters.

Refer to the tutorial for examples of both syntaxes.

MATCH_PHRASE function

edit

Use the MATCH_PHRASE function to perform a match_phrase query on the specified field. This is equivalent to using the match_phrase query in Query DSL.

For exact phrase matching rather than individual word matching, use MATCH_PHRASE.

Query string (QSTR) function

edit

The qstr function provides the same functionality as the Query DSL’s query_string query. This enables advanced search patterns with wildcards, boolean logic, and multi-field searches.

For complete details, refer to the Query DSL query_string docs.

KQL function

edit

Use the KQL function to use the Kibana Query Language in your ES|QL queries.

For migrating queries from other Kibana interfaces, the KQL function preserves existing query syntax and allows gradual migration to ES|QL without rewriting existing Kibana queries.

Advanced search capabilities

edit

Semantic search

edit

Semantic search leverages machine learning models to understand the meaning of text, enabling more accurate and context-aware search results.

In ES|QL, you can perform semantic searches on semantic_text field types using the same match syntax as full-text search.

Refer to semantic search with semantic_text for an example or follow the tutorial.

Hybrid search

edit

Hybrid search combines lexical and semantic search with custom weights to leverage both exact keyword matching and semantic understanding.

Refer to hybrid search with semantic_text for an example or follow the tutorial.

Next steps

edit

Tutorials and how-to guides

edit

Technical reference

edit

Related blog posts

edit
« ES|QL REST API Using ES|QL in Kibana »