This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« ES|QL REST API Using ES|QL in Kibana »
Elastic Docs ›Elasticsearch Guide [8.x] ›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 functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

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

Prefer to get started with a hands-on tutorial? Check out Tutorial: Search and filter with ES|QL.

The following table summarizes the key search features available in ES|QL and when they were introduced.

Feature Available since Description

Full text search functions

8.17

Perform basic text searches with match function and match operator (:)

Query string function

8.17

Execute complex queries with qstr using Query String syntax

Relevance scoring

8.18/9.0

Calculate and sort by relevance with METADATA _score

Enhanced match options

8.18/9.0

Configure text searches with additional parameters for the match function

Kibana Query Language

8.18/9.0

Use Kibana Query Language with kql function

Semantic search

8.18/9.0

Perform semantic searches on semantic_text field types

Hybrid search

8.18/9.0

Combine lexical and semantic search approaches with custom weights

Filtering vs. searching

edit

ES|QL can be used for both simple filtering and relevance-based searching:

  • Filtering removes non-matching documents without calculating relevance scores
  • Searching both filters documents and ranks them by how well they match the query

Note that filtering is faster than searching, because it doesn’t require score calculations.

Relevance scoring

edit

To get the most relevant results first, you need to use METADATA _score and sort by score. For example:

FROM books METADATA _score
| WHERE match(title, "Shakespeare") OR match(plot, "Shakespeare")
| SORT _score DESC

How _score works

edit

When working with relevance scoring in ES|QL:

  • If you don’t include METADATA _score in your query, this only performs filtering operations with no relevance calculation.
  • When you include METADATA _score, any search function included in WHERE conditions contribute to the relevance score. This means that every occurrence of MATCH, QSTR and KQL will affect the score.
  • Filtering operations that are not search functions, like range conditions and exact matches, don’t affect the score.
  • Including METADATA _score doesn’t automatically sort your results by relevance. You must explicitly use SORT _score DESC or SORT _score ASC to order your results by relevance.

Full text search

edit

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 operator syntax (:) for simple text matching with default parameters.

FROM logs | WHERE match(message, "connection error")

Use the match() function syntax when you need to pass additional parameters:

FROM products | WHERE match(name, "laptop", { "boost": 2.0 })

These full-text functions address several key limitations that existed for text filtering in ES|QL:

  • They work directly on multivalued fields, returning results when any value in a multivalued field matches the query
  • They leverage analyzers, ensuring the query is analyzed with the same process as the indexed data (enabling case-insensitive matching, ASCII folding, stopword removal, and synonym support)
  • They are highly performant, using Lucene index structures rather than pattern matching or regular expressions to locate terms in your data

Refer to this blog for more context: Introducing full text filtering in ES|QL.

See Match field parameters for more advanced options using match.

These queries match documents but don’t automatically sort by relevance. To get the most relevant results first, you need to use METADATA _score and sort by score. See Relevance scoring for more information.

Query string function (QSTR)

edit

The qstr function provides the same functionality as the Query DSL’s query_string query. This is for advanced use cases, such as wildcard searches, searches across multiple fields, and more.

FROM articles METADATA _score
| WHERE QSTR("(new york city) OR (big apple)")
| SORT _score DESC
| LIMIT 10

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

Kibana Query Language function (KQL)

edit

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

FROM logs*
| WHERE KQL("http.request.method:GET AND agent.type:filebeat")

The kql function is useful when transitioning queries from Kibana’s Discover, Dashboard, or other interfaces that use KQL. This will allow you to gradually migrate queries to ES|QL without needing to rewrite them all at once.

Semantic search

edit

You can perform semantic searches over semantic_text field types using the same match syntax as full-text search.

This example uses the match operator ::

FROM articles METADATA _score
| WHERE semantic_content:"What are the impacts of climate change on agriculture?"
| SORT _score DESC

This example uses the match function:

FROM articles METADATA _score
| WHERE match(semantic_content, "What are the impacts of climate change on agriculture?")
| SORT _score DESC

Hybrid search

edit

Combine traditional and semantic search with custom weights:

FROM books METADATA _score
| WHERE match(semantic_title, "fantasy adventure", { "boost": 0.75 })
    OR match(title, "fantasy adventure", { "boost": 0.25 })
| SORT _score DESC

Limitations

edit

Refer to ES|QL limitations for a list of known limitations.

Next steps

edit

Tutorials and how-to guides

edit

Technical reference

edit

Background concepts

edit

Related blog posts

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