From 6847a3473cd9582a1c1933d1f2ad60f8616225aa Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 19 Jun 2025 12:06:39 +0200 Subject: [PATCH 01/11] Update ESQL for Search landing page, tutorial for 9.1 --- solutions/search/esql-for-search.md | 160 +++++++------------ solutions/search/esql-search-tutorial.md | 195 +++++++++++++++++------ 2 files changed, 197 insertions(+), 158 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 304d0438eb..68aac79e08 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -16,162 +16,112 @@ products: This page provides an overview of how to use {{esql}} for search use cases. ::::{tip} -Prefer to get started with a hands-on tutorial? Check out [Search and filter with {{esql}}](esql-search-tutorial.md). +For a hands-on tutorial check out [Search and filter with {{esql}}](esql-search-tutorial.md). :::: - -## Overview +## {{esql}} search quick reference The following table summarizes the key search features available in [{{esql}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced. -| Feature | Available since | Description | -|---------|----------------|-------------| -| [Full text search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md) | 8.17 | Perform basic text searches with `MATCH` function or match operator (`:`) | -| [Query string function](#esql-for-search-query-string) | 8.17 | Execute complex queries with `QSTR` using Query String syntax | -| [Relevance scoring](#esql-for-search-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](#esql-for-search-kql) | 8.18/9.0 | Use Kibana Query Language with the `KQL` function | -| [Semantic search](#esql-for-search-semantic) | 8.18/9.0 | Perform semantic searches on `semantic_text` field types | -| [Hybrid search](#esql-for-search-hybrid) | 8.18/9.0 | Combine lexical and semantic search approaches with custom weights | - -## Filtering vs. searching [esql-filtering-vs-searching] +| Feature | Description | Available since | +|---------|-------------|----------------| +| [Match function/operator](#esql-for-search-match-function-operator) | Perform basic text searches with `MATCH` function or match operator (`:`) | 8.17 | +| [Match phrase function](#esql-for-search-match-phrase) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | +| [Query string function](#esql-for-search-query-string) | Execute complex queries with `QSTR` using Query String syntax | 8.17 | +| [Relevance scoring](#esql-for-search-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | +| [Semantic search](#esql-for-search-semantic) | Perform semantic searches on `semantic_text` field types | 8.18/9.0 | +| [Hybrid search](#esql-for-search-hybrid) | Combine lexical and semantic search approaches with custom weights | 8.18/9.0 | +| [Kibana Query Language](#esql-for-search-kql) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | -{{esql}} can be used for both simple filtering and relevance-based searching: +## How search works in {{esql}} -* **Filtering** removes non-matching documents without calculating relevance scores -* **Searching** both filters documents and ranks them by how well they match the query +{{esql}} 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. -Note that filtering is faster than searching, because it doesn't require score calculations. +**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. -### Relevance scoring [esql-for-search-scoring] +**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. -To get the most relevant results first, you need to use `METADATA _score` and sort by score. For example: +**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 -```esql -FROM books METADATA _score -| WHERE match(title, "Shakespeare") OR match(plot, "Shakespeare") -| SORT _score DESC -``` +**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 -### How `_score` works [esql-for-search-how-scoring-works] +{{esql}}'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. -When working with relevance scoring in {{esql}}: +### Relevance scoring -* 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. +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. -## Full text search [esql-for-search-full-text] +**Without `METADATA _score`**: All operations are filtering-only, even `MATCH`, `QSTR`, and `KQL` functions. Documents either match or don't match - no ranking occurs. -### `MATCH` function and operator [esql-for-search-match-function-operator] +**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. -{{esql}} offers two syntax options for `match`, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. +This gives you full control over when to use fast filtering versus slower but more powerful relevance-based searching. -Use the compact operator syntax (`:`) for simple text matching with default parameters. +## Search functions -```esql -FROM logs | WHERE message: "connection error" -``` +The following functions provide text-based search capabilities in ES|QL with different levels of precision and control. -Use the `match()` function syntax when you need to pass additional parameters: +### `MATCH` function and operator -```esql -FROM products | WHERE match(name, "laptop", { "boost": 2.0 }) -``` +ES|QL offers two syntax options for `match`, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. -These full-text functions address several key limitations that existed for text filtering in {{esql}}: +Use the compact [operator syntax (`:`)](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator) for simple text matching with default parameters. -* 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 +Use the [`MATCH` function syntax](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. -Refer to this blog for more context: [Introducing full text filtering in {{esql}}](https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr). +Refer to the [tutorial](esql-search-tutorial.md#step-3-basic-search-operations) for examples of both syntaxes. -::::{tip} -See [Match field parameters](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) for more advanced options using match. -:::: +### `MATCH_PHRASE` function -::::{important} -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](#esql-for-search-scoring) for more information. -:::: +Use the [`MATCH_PHRASE` function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match_phrase) to perform a `match_phrase` query on the specified field. This is equivalent to using the [match_phrase query](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query-phrase.md) in Query DSL. -### Query string (`QSTR`) function [esql-for-search-query-string] +For exact phrase matching rather than individual word matching, use `MATCH_PHRASE`. -The [`qstr` function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-qstr) 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. +### Query string (`QSTR`) function -```esql -FROM articles METADATA _score -| WHERE QSTR("(new york city) OR (big apple)") -| SORT _score DESC -| LIMIT 10 -``` +The [`qstr` function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-qstr) 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](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md). -### `KQL` function [esql-for-search-kql] - -Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your {{esql}} queries: +### `KQL` function -```esql -FROM logs* -| WHERE KQL("http.request.method:GET AND agent.type:filebeat") -``` +Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your ES|QL queries. -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 {{esql}} without needing to rewrite them all at once. +For migrating queries from other Kibana interfaces, the `KQL` function preserves existing query syntax and allows gradual migration to ES|QL without rewriting queries. -## Semantic search [esql-for-search-semantic] +## Advanced search capabilities -You can perform semantic searches over [`semantic_text`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. +### Semantic search -This example uses the match operator `:`: +[Semantic search](/solutions/search/semantic-search.md) leverages machine learning models to understand the meaning of text, enabling more accurate and context-aware search results. -```esql -FROM articles METADATA _score -| WHERE semantic_content: "What are the impacts of climate change on agriculture?" -| SORT _score DESC -``` +In ES|QL, you can perform semantic searches on [`semantic_text`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. -This example uses the match function: +Refer to [semantic search with semantic_text](/solutions/search/semantic-search/semantic-search-semantic-text.md) for an example or follow the [tutorial](esql-search-tutorial.md#step-5-semantic-search-and-hybrid-search). -```esql -FROM articles METADATA _score -| WHERE match(semantic_content, "What are the impacts of climate change on agriculture?") -| SORT _score DESC -``` +### Hybrid search -## Hybrid search [esql-for-search-hybrid] +[Hybrid search](/solutions/search/hybrid-search.md) combines lexical and semantic search with custom weights to leverage both exact keyword matching and semantic understanding. -[Hybrid search](/solutions/search/hybrid-search.md) combines lexical and semantic search with custom weights: - -```esql -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 [esql-for-search-limitations] - -Refer to [{{esql}} limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search) for a list of known limitations. +Refer to [hybrid search with semantic_text](hybrid-semantic-text.md) for an example or follow the [tutorial](esql-search-tutorial.md#step-5-semantic-search-and-hybrid-search). ## Next steps [esql-for-search-next-steps] ### Tutorials and how-to guides [esql-for-search-tutorials] -- [Search and filter with {{esql}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}} -- [Semantic search with semantic_text](semantic-search/semantic-search-semantic-text.md): Learn how to use the `semantic_text` field type +- [Search and filter with {{esql}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}}, with concrete examples of the functionalities described in this page ### Technical reference [esql-for-search-reference] - [Search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md): Complete reference for all search functions -- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search in {{esql}} - -### Background concepts [esql-for-search-concepts] - -- [Analysis](/manage-data/data-store/text-analysis.md): Learn how text is processed for full-text search -- [Semantic search](semantic-search.md): Get an overview of semantic search in Elasticsearch -- [Query vs filter context](elasticsearch://reference/query-languages/query-dsl/query-filter-context.md): Understand the difference between query and filter contexts in Elasticsearch +- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search functions in {{esql}} ### Related blog posts [esql-for-search-blogs] diff --git a/solutions/search/esql-search-tutorial.md b/solutions/search/esql-search-tutorial.md index 22f4e7b4a6..e39c335231 100644 --- a/solutions/search/esql-search-tutorial.md +++ b/solutions/search/esql-search-tutorial.md @@ -145,61 +145,103 @@ POST /cooking_blog/_bulk?refresh=wait_for {"title":"Crispy Oven-Fried Chicken","description":"Get that perfect crunch without the deep fryer! This oven-fried chicken recipe delivers crispy, juicy results every time. A healthier take on the classic comfort food.","author":"Maria Rodriguez","date":"2023-05-20","category":"Main Course","tags":["chicken","oven-fried","healthy"],"rating":4.9} ``` -## Step 3: Perform basic full-text searches +## Step 3: Basic search operations -Full-text search involves executing text-based queries across one or more document fields. These queries calculate a relevance score for each matching document, based on how closely the document's content aligns with the search terms. Elasticsearch offers various query types, each with its own method for matching text and relevance scoring. +Full-text search involves executing text-based queries across one or more document fields. In this section, we'll start with simple text matching and build up to understanding how search results are ranked. -:::{tip} -{{esql}} provides two ways to perform full-text searches: +{{esql}} provides multiple functions for full-text search, including `MATCH`, `MATCH_PHRASE`, and `QSTR`. For basic text matching, you can use either: 1. Full [match function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) syntax: `match(field, "search terms")` -1. Compact syntax using the [match operator `:`](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator): `field:"search terms"` +2. Compact syntax using the [match operator `:`](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator): `field:"search terms"` -Both are equivalent and can be used interchangeably. The compact syntax is more concise, while the function syntax allows for more configuration options. We'll use the compact syntax in most examples for brevity. +Both are equivalent for basic matching and can be used interchangeably. The compact syntax is more concise, while the function syntax allows for more configuration options. We'll use the compact syntax in most examples for brevity. -Refer to the [match function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) reference docs for advanced parameters available with the function syntax. -::: +Refer to the [`MATCH` function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) reference docs for advanced parameters available with the function syntax. -### Basic full-text query +### Make your first search query -Here's how to search the `description` field for "fluffy pancakes": +Let's start with the simplest possible search - looking for documents that contain specific words: ```esql -FROM cooking_blog # Specify the index to search -| WHERE description:"fluffy pancakes" # Full-text search with OR logic by default -| LIMIT 1000 # Return up to 1000 results +FROM cooking_blog +| WHERE description:"fluffy pancakes" +| LIMIT 1000 ``` -:::{note} -The results ordering isn't by relevance, as we haven't requested the `_score` metadata field. We'll cover relevance scoring in the next section. -::: +This query searches the `description` field for documents containing either "fluffy" OR "pancakes" (or both). By default, {{esql}} uses OR logic between search terms, so it will match documents that contain any of the specified words. -By default, like the Query DSL `match` query, {{esql}} uses `OR` logic between terms. This means it will match documents that contain either "fluffy" or "pancakes", or both, in the description field. +### Control which fields appear in results -:::{tip} -You can control which fields to include in the response using the `KEEP` command: +You can specify exactly which fields to include in your results using the `KEEP` command: ```esql FROM cooking_blog | WHERE description:"fluffy pancakes" -| KEEP title, description, rating # Select only specific fields to include in response +| KEEP title, description, rating +| LIMIT 1000 +``` + +This helps reduce the amount of data returned and focuses on the information you need. + +### Understand relevance scoring + +Search results can be ranked by how well they match your query. To calaculate and use relevance scores, you need to explicitly request the `_score` metadata: + +```esql +FROM cooking_blog METADATA _score +| WHERE description:"fluffy pancakes" +| KEEP title, description, _score +| SORT _score DESC | LIMIT 1000 ``` + +Notice two important things: +1. `METADATA _score` tells {{esql}} to include relevance scores in the results +2. `SORT _score DESC` orders results by relevance (highest scores first) + +If you don't include `METADATA _score` in your query, you won't see relevance scores in your results. This means you won't be able to sort by relevance or filter based on relevance scores. + +Without explicit sorting, results aren't ordered by relevance even when scores are calculated. If you want the most relevant results first, you must sort by `_score`, by explicitly using `SORT _score DESC` or `SORT _score ASC`. + +:::{tip} +When you include `METADATA _score`, search functions included in `WHERE` conditions contribute to the relevance score. Filtering operations (like range conditions and exact matches) don't affect the score. ::: -### Require all terms in a match query +### Find exact matches + +Sometimes you need exact matches rather than full-text search. Use the `.keyword` field for case-sensitive exact matching: + +```esql +FROM cooking_blog +| WHERE category.keyword == "Breakfast" # Exact match (case-sensitive) +| KEEP title, category, rating +| SORT rating DESC +| LIMIT 1000 +``` + +This is fundamentally different from full-text search - it's a binary yes/no filter that doesn't affect relevance scoring. + +## Step 4: Search precision control + +Now that you understand basic searching, let's explore how to control the precision of your text matches. + +### Require all search terms (AND logic) -Sometimes you need to require that all search terms appear in the matching documents. Here's how to do that using the function syntax with the `operator` parameter: +By default, searches with match use OR logic between terms. To require ALL terms to match, use the function syntax with the `operator` parameter to specify AND logic: ```esql FROM cooking_blog -| WHERE match(description, "fluffy pancakes", {"operator": "AND"}) # Require ALL terms to match +| WHERE match(description, "fluffy pancakes", {"operator": "AND"}) | LIMIT 1000 ``` This stricter search returns *zero hits* on our sample data, as no document contains both "fluffy" and "pancakes" in the description. -### Specify a minimum number of terms to match +:::{note} +The `MATCH` function with AND logic doesn't require terms to be adjacent or in order. It only requires that all terms appear somewhere in the field. Use `MATCH_PHRASE` to [search for exact phrases](#search-for-exact-phrases). +::: + +### Set a minimum number of terms to match Sometimes requiring all terms is too strict, but the default OR behavior is too lenient. You can specify a minimum number of terms that must match: @@ -211,7 +253,20 @@ FROM cooking_blog This query searches the title field to match at least 2 of the 3 terms: "fluffy", "pancakes", or "breakfast". -## Step 4: Semantic search and hybrid search +### Search for exact phrases + +When you need to find documents containing an exact sequence of words, use the `MATCH_PHRASE` function: + +```esql +FROM cooking_blog +| WHERE MATCH_PHRASE(description, "rich and creamy") +| KEEP title, description +| LIMIT 1000 +``` + +This query will only match documents where the words "rich" and "creamy" appear exactly in that order in the description field. + +## Step 5: Semantic search and hybrid search ### Index semantic content @@ -271,9 +326,36 @@ FROM cooking_blog METADATA _score | LIMIT 5 ``` -## Step 5: Search across multiple fields at once +This query searches the `semantic_description` field for documents that are semantically similar to "easy to prepare vegetarian meals" with a higher weight, while also matching the `tags` field for "vegetarian" with a lower weight. The results are sorted by relevance score. + +Learn how to combine these with complex criteria in [Step 8](#step-8-complex-search-solutions). + +## Step 6: Advanced search features + +Once you're comfortable with basic search precision, these advanced features give you powerful search capabilities. + +### Use query string for complex patterns + +The `QSTR` function enables powerful search patterns using a compact query language. It's ideal for when you need wildcards, fuzzy matching, and boolean logic in a single expression: + +```esql +FROM cooking_blog +| WHERE QSTR(description, "fluffy AND pancak* OR (creamy -vegan)") +| KEEP title, description +| LIMIT 1000 +``` + +Query string syntax lets you: +- Use boolean operators: `AND`, `OR`, `-` (NOT) +- Apply wildcards: `pancak*` matches "pancake" and "pancakes" +- Enable fuzzy matching: `pancake~1` for typo tolerance +- Group terms: `(thai AND curry) OR pasta` +- Search exact phrases: `"fluffy pancakes"` +- Search across fields: `QSTR("title,description", "pancake OR (creamy AND rich)")` + +### Search across multiple fields -When users enter a search query, they often don't know (or care) whether their search terms appear in a specific field. {{esql}} provides ways to search across multiple fields simultaneously: +When users enter a search query, they often don't know (or care) whether their search terms appear in a specific field. You can search across multiple fields simultaneously: ```esql FROM cooking_blog @@ -283,41 +365,35 @@ FROM cooking_blog This query searches for "vegetarian curry" across the title, description, and tags fields. Each field is treated with equal importance. -However, in many cases, matches in certain fields (like the title) might be more relevant than others. We can adjust the importance of each field using scoring: +### Weight different fields + +In many cases, matches in certain fields (like the title) might be more relevant than others. You can adjust the importance of each field using boost scoring: ```esql -FROM cooking_blog METADATA _score # Request _score metadata for relevance-based results +FROM cooking_blog METADATA _score | WHERE match(title, "vegetarian curry", {"boost": 2.0}) # Title matches are twice as important OR match(description, "vegetarian curry") OR match(tags, "vegetarian curry") -| KEEP title, description, tags, _score # Include relevance score in results -| SORT _score DESC # You must explicitly sort by `_score` to see relevance-based results +| KEEP title, description, tags, _score +| SORT _score DESC | LIMIT 1000 ``` -:::{tip} -When working with relevance scoring in ES|QL, it's important to understand `_score`. If you don't include `METADATA _score` in your query, you won't see relevance scores in your results. This means you won't be able to sort by relevance or filter based on relevance scores. - -When you include `METADATA _score`, search functions included in WHERE conditions contribute to the relevance score. Filtering operations (like range conditions and exact matches) don't affect the score. - -If you want the most relevant results first, you must sort by `_score`, by explicitly using `SORT _score DESC` or `SORT _score ASC`. -::: - -## Step 6: Filter and find exact matches +## Step 7: Filtering and exact matching Filtering allows you to narrow down your search results based on exact criteria. Unlike full-text searches, filters are binary (yes/no) and do not affect the relevance score. Filters execute faster than queries because excluded results don't need to be scored. +### Basic filtering by category + ```esql FROM cooking_blog -| WHERE category.keyword == "Breakfast" # Exact match using keyword field(case-sensitive) +| WHERE category.keyword == "Breakfast" # Exact match using keyword field | KEEP title, author, rating, tags | SORT rating DESC | LIMIT 1000 ``` -Note the use of `category.keyword` here. This refers to the [`keyword`](elasticsearch://reference/elasticsearch/mapping-reference/keyword.md) multi-field of the `category` field, ensuring an exact, case-sensitive match. - -### Search for posts within a date range +### Date range filtering Often users want to find content published within a specific time frame: @@ -328,9 +404,21 @@ FROM cooking_blog | LIMIT 1000 ``` -### Find exact matches +### Numerical range filtering -Sometimes users want to search for exact terms to eliminate ambiguity in their search results: +Filter by ratings or other numerical values: + +```esql +FROM cooking_blog +| WHERE rating >= 4.5 # Only highly-rated recipes +| KEEP title, author, rating, tags +| SORT rating DESC +| LIMIT 1000 +``` + +### Exact author matching + +Find recipes by a specific author: ```esql FROM cooking_blog @@ -340,11 +428,13 @@ FROM cooking_blog | LIMIT 1000 ``` -Like the `term` query in Query DSL, this has zero flexibility and is case-sensitive. +## Step 8: Complex search solutions + +Real-world search often requires combining multiple types of criteria. This section shows how to build sophisticated search experiences. -## Step 7: Combine multiple search criteria +### Combine filters with full-text search -Complex searches often require combining multiple search criteria: +Mix filters, full-text search, and custom scoring in a single query: ```esql FROM cooking_blog METADATA _score @@ -356,23 +446,22 @@ FROM cooking_blog METADATA _score | LIMIT 1000 ``` -### Combine relevance scoring with custom criteria +### Advanced relevance scoring -For more complex relevance scoring with combined criteria, you can use the `EVAL` command to calculate custom scores: +For complex relevance scoring with combined criteria, you can use the `EVAL` command to calculate custom scores: ```esql FROM cooking_blog METADATA _score | WHERE NOT category.keyword == "Dessert" | EVAL tags_concat = MV_CONCAT(tags.keyword, ",") # Convert multi-value field to string | WHERE tags_concat LIKE "*vegetarian*" AND rating >= 4.5 # Wildcard pattern matching -| WHERE match(title, "curry spicy", {"boost": 2.0}) OR match(description, "curry spicy") # Uses full text functions, will update _score metadata field +| WHERE match(title, "curry spicy", {"boost": 2.0}) OR match(description, "curry spicy") | EVAL category_boost = CASE(category.keyword == "Main Course", 1.0, 0.0) # Conditional boost | EVAL date_boost = CASE(DATE_DIFF("month", date, NOW()) <= 1, 0.5, 0.0) # Boost recent content | EVAL custom_score = _score + category_boost + date_boost # Combine scores | WHERE custom_score > 0 # Filter based on custom score | SORT custom_score DESC | LIMIT 1000 - ``` ## Learn more From ac59284cb788e83c7cbde872c396ba7c6e176912 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 19 Jun 2025 12:28:44 +0200 Subject: [PATCH 02/11] use present tense --- solutions/search/esql-search-tutorial.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/solutions/search/esql-search-tutorial.md b/solutions/search/esql-search-tutorial.md index e39c335231..52d45b9ac6 100644 --- a/solutions/search/esql-search-tutorial.md +++ b/solutions/search/esql-search-tutorial.md @@ -19,7 +19,7 @@ In this scenario, we're implementing search for a cooking blog. The blog contain ## Requirements -You'll need a running {{es}} cluster, together with {{kib}} to use the Dev Tools API Console. Refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) for deployment options. +You need a running {{es}} cluster, together with {{kib}} to use the Dev Tools API Console. Refer to [choose your deployment type](/deploy-manage/deploy.md#choosing-your-deployment-type) for deployment options. Want to get started quickly? Run the following command in your terminal to set up a [single-node local cluster in Docker](get-started.md): @@ -29,7 +29,7 @@ curl -fsSL https://elastic.co/start-local | sh ## Running {{esql}} queries -In this tutorial, you'll see {{esql}} examples in the following format: +In this tutorial, {{esql}} examples are displayed in the following format: ```esql FROM cooking_blog @@ -37,7 +37,7 @@ FROM cooking_blog | LIMIT 1000 ``` -If you want to run these queries in the [Dev Tools Console](/explore-analyze/query-filter/languages/esql-rest.md#esql-kibana-console), you'll need to use the following syntax: +If you want to run these queries in the [Dev Tools Console](/explore-analyze/query-filter/languages/esql-rest.md#esql-kibana-console), you need to use the following syntax: ```console POST /_query?format=txt @@ -147,14 +147,14 @@ POST /cooking_blog/_bulk?refresh=wait_for ## Step 3: Basic search operations -Full-text search involves executing text-based queries across one or more document fields. In this section, we'll start with simple text matching and build up to understanding how search results are ranked. +Full-text search involves executing text-based queries across one or more document fields. In this section, we start with simple text matching and build up to understanding how search results are ranked. {{esql}} provides multiple functions for full-text search, including `MATCH`, `MATCH_PHRASE`, and `QSTR`. For basic text matching, you can use either: 1. Full [match function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) syntax: `match(field, "search terms")` 2. Compact syntax using the [match operator `:`](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator): `field:"search terms"` -Both are equivalent for basic matching and can be used interchangeably. The compact syntax is more concise, while the function syntax allows for more configuration options. We'll use the compact syntax in most examples for brevity. +Both are equivalent for basic matching and can be used interchangeably. The compact syntax is more concise, while the function syntax allows for more configuration options. We use the compact syntax in most examples for brevity. Refer to the [`MATCH` function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) reference docs for advanced parameters available with the function syntax. @@ -168,7 +168,7 @@ FROM cooking_blog | LIMIT 1000 ``` -This query searches the `description` field for documents containing either "fluffy" OR "pancakes" (or both). By default, {{esql}} uses OR logic between search terms, so it will match documents that contain any of the specified words. +This query searches the `description` field for documents containing either "fluffy" OR "pancakes" (or both). By default, {{esql}} uses OR logic between search terms, so it matches documents that contain any of the specified words. ### Control which fields appear in results @@ -264,7 +264,7 @@ FROM cooking_blog | LIMIT 1000 ``` -This query will only match documents where the words "rich" and "creamy" appear exactly in that order in the description field. +This query only matches documents where the words "rich" and "creamy" appear exactly in that order in the description field. ## Step 5: Semantic search and hybrid search From eae2ac879d7b81b18b0f680803ee82a0e6f4adf7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 20 Jun 2025 13:38:31 +0200 Subject: [PATCH 03/11] fix on-page links --- solutions/search/esql-for-search.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 68aac79e08..9178ae58a5 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -25,13 +25,13 @@ The following table summarizes the key search features available in [{{esql}}](/ | Feature | Description | Available since | |---------|-------------|----------------| -| [Match function/operator](#esql-for-search-match-function-operator) | Perform basic text searches with `MATCH` function or match operator (`:`) | 8.17 | -| [Match phrase function](#esql-for-search-match-phrase) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | -| [Query string function](#esql-for-search-query-string) | Execute complex queries with `QSTR` using Query String syntax | 8.17 | -| [Relevance scoring](#esql-for-search-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | -| [Semantic search](#esql-for-search-semantic) | Perform semantic searches on `semantic_text` field types | 8.18/9.0 | -| [Hybrid search](#esql-for-search-hybrid) | Combine lexical and semantic search approaches with custom weights | 8.18/9.0 | -| [Kibana Query Language](#esql-for-search-kql) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | +| [Match function/operator](#match-function-and-operator) | Perform basic text searches with `MATCH` function or match operator (`:`) | 8.17 | +| [Match phrase function](#match_phrase-function) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | +| [Query string function](#query-string-qstr-function) | Execute complex queries with `QSTR` using Query String syntax | 8.17 | +| [Relevance scoring](#relevance-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | +| [Semantic search](#semantic-search) | Perform semantic searches on `semantic_text` field types | 8.18/9.0 | +| [Hybrid search](#hybrid-search) | Combine lexical and semantic search approaches with custom weights | 8.18/9.0 | +| [Kibana Query Language](#kql-function) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | ## How search works in {{esql}} From fc82eb1c4c0d6c4b53a18d2b03b3c5447452d130 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 24 Jun 2025 09:37:14 +0200 Subject: [PATCH 04/11] Update applies_to --- solutions/search/esql-search-tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/esql-search-tutorial.md b/solutions/search/esql-search-tutorial.md index 52d45b9ac6..2f73595a42 100644 --- a/solutions/search/esql-search-tutorial.md +++ b/solutions/search/esql-search-tutorial.md @@ -1,7 +1,7 @@ --- applies_to: - stack: preview 9.0 - serverless: preview + stack: preview 9.0, ga 9.1 + serverless: ga navigation_title: Search and filter with ES|QL --- From d79f88208c1c592748afb5175281f5f82667e139 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Jul 2025 12:27:53 +0200 Subject: [PATCH 05/11] Updates per Carlos review --- solutions/search/esql-for-search.md | 9 +++++---- solutions/search/esql-search-tutorial.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 9178ae58a5..d97737d982 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -21,17 +21,17 @@ For a hands-on tutorial check out [Search and filter with {{esql}}](esql-search- ## {{esql}} search quick reference -The following table summarizes the key search features available in [{{esql}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced. +The following table summarizes the key search features available in [{{esql}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced, organized chronologically by release. | Feature | Description | Available since | |---------|-------------|----------------| | [Match function/operator](#match-function-and-operator) | Perform basic text searches with `MATCH` function or match operator (`:`) | 8.17 | -| [Match phrase function](#match_phrase-function) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | | [Query string function](#query-string-qstr-function) | Execute complex queries with `QSTR` using Query String syntax | 8.17 | | [Relevance scoring](#relevance-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | | [Semantic search](#semantic-search) | Perform semantic searches on `semantic_text` field types | 8.18/9.0 | | [Hybrid search](#hybrid-search) | Combine lexical and semantic search approaches with custom weights | 8.18/9.0 | | [Kibana Query Language](#kql-function) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | +| [Match phrase function](#match_phrase-function) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | ## How search works in {{esql}} @@ -51,6 +51,7 @@ The following table summarizes the key search features available in [{{esql}}](/ - 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](elasticsearch://reference/elasticsearch/mapping-reference/analyzer.md) or [synonyms](/solutions/search/full-text/search-with-synonyms.md) {{esql}}'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. @@ -60,7 +61,7 @@ To get relevance-ranked results, you must explicitly request scoring with `METAD **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. +**With `METADATA _score`**: [Search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md) 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. @@ -94,7 +95,7 @@ For complete details, refer to the [Query DSL `query_string` docs](elasticsearch Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) 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 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 diff --git a/solutions/search/esql-search-tutorial.md b/solutions/search/esql-search-tutorial.md index 2f73595a42..918507211f 100644 --- a/solutions/search/esql-search-tutorial.md +++ b/solutions/search/esql-search-tutorial.md @@ -264,7 +264,7 @@ FROM cooking_blog | LIMIT 1000 ``` -This query only matches documents where the words "rich" and "creamy" appear exactly in that order in the description field. +This query only matches documents where the words "rich and creamy" appear exactly in that order in the description field. ## Step 5: Semantic search and hybrid search From 1664d4c03d7755b4e458e17df1812959113cab74 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Jul 2025 12:34:01 +0200 Subject: [PATCH 06/11] restore explicit id --- solutions/search/esql-for-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index d97737d982..e9e10adddc 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -55,7 +55,7 @@ The following table summarizes the key search features available in [{{esql}}](/ {{esql}}'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 +### Relevance scoring [esql-for-search-scoring] 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. From 444ea92daaa914932d208efa2ae05c7332969211 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 2 Jul 2025 13:46:32 +0200 Subject: [PATCH 07/11] ok fine whatever docs-builder you got me --- solutions/search/esql-for-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index e9e10adddc..8773bb20de 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -27,7 +27,7 @@ The following table summarizes the key search features available in [{{esql}}](/ |---------|-------------|----------------| | [Match function/operator](#match-function-and-operator) | Perform basic text searches with `MATCH` function or match operator (`:`) | 8.17 | | [Query string function](#query-string-qstr-function) | Execute complex queries with `QSTR` using Query String syntax | 8.17 | -| [Relevance scoring](#relevance-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | +| [Relevance scoring](#esql-for-search-scoring) | Calculate and sort by relevance with `METADATA _score` | 8.18/9.0 | | [Semantic search](#semantic-search) | Perform semantic searches on `semantic_text` field types | 8.18/9.0 | | [Hybrid search](#hybrid-search) | Combine lexical and semantic search approaches with custom weights | 8.18/9.0 | | [Kibana Query Language](#kql-function) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | From 6b51b3deeeea8ae71862daaf84e5a9c8e83892da Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 7 Jul 2025 16:52:30 +0200 Subject: [PATCH 08/11] Use variable, incorporate Bogi's suggestion --- solutions/search/esql-for-search.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 8773bb20de..6d70d3eea9 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -67,15 +67,14 @@ This gives you full control over when to use fast filtering versus slower but mo ## Search functions -The following functions provide text-based search capabilities in ES|QL with different levels of precision and control. +The following functions provide text-based search capabilities in {esql} with different levels of precision and control. ### `MATCH` function and operator -ES|QL offers two syntax options for `match`, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. +{esql} offers two syntax options for match, which replicate the functionality of [match](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-match-query) queries in Query DSL. -Use the compact [operator syntax (`:`)](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator) for simple text matching with default parameters. - -Use the [`MATCH` function syntax](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. +- Use the compact [operator syntax (:)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/operators#esql-match-operator) for simple text matching with default parameters. +- Use the [MATCH function syntax](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/search-functions#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. Refer to the [tutorial](esql-search-tutorial.md#step-3-basic-search-operations) for examples of both syntaxes. @@ -93,9 +92,9 @@ For complete details, refer to the [Query DSL `query_string` docs](elasticsearch ### `KQL` function -Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your ES|QL queries. +Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your {esql} 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. +For migrating queries from other Kibana interfaces, the `KQL` function preserves existing query syntax and allows gradual migration to {esql} without rewriting existing Kibana queries. ## Advanced search capabilities @@ -103,7 +102,7 @@ For migrating queries from other Kibana interfaces, the `KQL` function preserves [Semantic search](/solutions/search/semantic-search.md) 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`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. +In {esql}, you can perform semantic searches on [`semantic_text`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. Refer to [semantic search with semantic_text](/solutions/search/semantic-search/semantic-search-semantic-text.md) for an example or follow the [tutorial](esql-search-tutorial.md#step-5-semantic-search-and-hybrid-search). From 824d8fa095457fe643617789ec0f3f7db589f427 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 7 Jul 2025 16:56:20 +0200 Subject: [PATCH 09/11] fix urls --- solutions/search/esql-for-search.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 6d70d3eea9..653f52a435 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -71,10 +71,10 @@ The following functions provide text-based search capabilities in {esql} with di ### `MATCH` function and operator -{esql} offers two syntax options for match, which replicate the functionality of [match](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-match-query) queries in Query DSL. +{esql} offers two syntax options for match, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. -- Use the compact [operator syntax (:)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/operators#esql-match-operator) for simple text matching with default parameters. -- Use the [MATCH function syntax](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/search-functions#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. +- Use the compact [operator syntax (:)](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator) for simple text matching with default parameters. +- Use the [MATCH function syntax](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. Refer to the [tutorial](esql-search-tutorial.md#step-3-basic-search-operations) for examples of both syntaxes. From 8a4af09a57445745aeedff1dc33c0f2c7872785c Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 7 Jul 2025 16:59:38 +0200 Subject: [PATCH 10/11] should have gone back to bed --- solutions/search/esql-for-search.md | 34 ++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 653f52a435..d7a011a202 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -11,17 +11,17 @@ products: % ℹ️ 8.x version of this doc lives in elasticsearch repo % https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/esql/esql-for-search.asciidoc -# {{esql}} for search [esql-for-search] +# {{{esql}}} for search [esql-for-search] -This page provides an overview of how to use {{esql}} for search use cases. +This page provides an overview of how to use {{{esql}}} for search use cases. ::::{tip} -For a hands-on tutorial check out [Search and filter with {{esql}}](esql-search-tutorial.md). +For a hands-on tutorial check out [Search and filter with {{{esql}}}](esql-search-tutorial.md). :::: -## {{esql}} search quick reference +## {{{esql}}} search quick reference -The following table summarizes the key search features available in [{{esql}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced, organized chronologically by release. +The following table summarizes the key search features available in [{{{esql}}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced, organized chronologically by release. | Feature | Description | Available since | |---------|-------------|----------------| @@ -33,9 +33,9 @@ The following table summarizes the key search features available in [{{esql}}](/ | [Kibana Query Language](#kql-function) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | | [Match phrase function](#match_phrase-function) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | -## How search works in {{esql}} +## How search works in {{{esql}}} -{{esql}} 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. +{{{esql}}} 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. @@ -53,7 +53,7 @@ The following table summarizes the key search features available in [{{esql}}](/ - Any scenario where you want the "best" matches first - You want to use [analyzers](elasticsearch://reference/elasticsearch/mapping-reference/analyzer.md) or [synonyms](/solutions/search/full-text/search-with-synonyms.md) -{{esql}}'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. +{{{esql}}}'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 [esql-for-search-scoring] @@ -67,11 +67,11 @@ This gives you full control over when to use fast filtering versus slower but mo ## Search functions -The following functions provide text-based search capabilities in {esql} with different levels of precision and control. +The following functions provide text-based search capabilities in {{esql}} with different levels of precision and control. ### `MATCH` function and operator -{esql} offers two syntax options for match, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. +{{esql}} offers two syntax options for match, which replicate the functionality of [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md) queries in Query DSL. - Use the compact [operator syntax (:)](elasticsearch://reference/query-languages/esql/functions-operators/operators.md#esql-match-operator) for simple text matching with default parameters. - Use the [MATCH function syntax](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-match) for more control over the query, such as specifying analyzers, fuzziness, and other parameters. @@ -92,9 +92,9 @@ For complete details, refer to the [Query DSL `query_string` docs](elasticsearch ### `KQL` function -Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your {esql} queries. +Use the [KQL function](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md#esql-kql) to use the [Kibana Query Language](/explore-analyze/query-filter/languages/kql.md) in your {{esql}} queries. -For migrating queries from other Kibana interfaces, the `KQL` function preserves existing query syntax and allows gradual migration to {esql} without rewriting existing Kibana queries. +For migrating queries from other Kibana interfaces, the `KQL` function preserves existing query syntax and allows gradual migration to {{esql}} without rewriting existing Kibana queries. ## Advanced search capabilities @@ -102,7 +102,7 @@ For migrating queries from other Kibana interfaces, the `KQL` function preserves [Semantic search](/solutions/search/semantic-search.md) leverages machine learning models to understand the meaning of text, enabling more accurate and context-aware search results. -In {esql}, you can perform semantic searches on [`semantic_text`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. +In {{esql}}, you can perform semantic searches on [`semantic_text`](elasticsearch://reference/elasticsearch/mapping-reference/semantic-text.md) field types using the same match syntax as full-text search. Refer to [semantic search with semantic_text](/solutions/search/semantic-search/semantic-search-semantic-text.md) for an example or follow the [tutorial](esql-search-tutorial.md#step-5-semantic-search-and-hybrid-search). @@ -116,14 +116,14 @@ Refer to [hybrid search with semantic_text](hybrid-semantic-text.md) for an exam ### Tutorials and how-to guides [esql-for-search-tutorials] -- [Search and filter with {{esql}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}}, with concrete examples of the functionalities described in this page +- [Search and filter with {{{esql}}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{{esql}}}, with concrete examples of the functionalities described in this page ### Technical reference [esql-for-search-reference] - [Search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md): Complete reference for all search functions -- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search functions in {{esql}} +- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search functions in {{{esql}}} ### Related blog posts [esql-for-search-blogs] -- [{{esql}}, you know for Search](https://www.elastic.co/search-labs/blog/esql-introducing-scoring-semantic-search): Introducing scoring and semantic search -- [Introducing full text filtering in {{esql}}](https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr): Overview of {{esql}}'s text filtering capabilities +- [{{{esql}}}, you know for Search](https://www.elastic.co/search-labs/blog/esql-introducing-scoring-semantic-search): Introducing scoring and semantic search +- [Introducing full text filtering in {{{esql}}}](https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr): Overview of {{{esql}}}'s text filtering capabilities From 8afd0f64c0fec165540f14121736676e7a6364c1 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 7 Jul 2025 17:00:51 +0200 Subject: [PATCH 11/11] =?UTF-8?q?=F0=9F=AB=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- solutions/search/esql-for-search.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index d7a011a202..245c5730b3 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -11,17 +11,17 @@ products: % ℹ️ 8.x version of this doc lives in elasticsearch repo % https://github.com/elastic/elasticsearch/blob/8.x/docs/reference/esql/esql-for-search.asciidoc -# {{{esql}}} for search [esql-for-search] +# {{esql}} for search [esql-for-search] -This page provides an overview of how to use {{{esql}}} for search use cases. +This page provides an overview of how to use {{esql}} for search use cases. ::::{tip} -For a hands-on tutorial check out [Search and filter with {{{esql}}}](esql-search-tutorial.md). +For a hands-on tutorial check out [Search and filter with {{esql}}](esql-search-tutorial.md). :::: -## {{{esql}}} search quick reference +## {{esql}} search quick reference -The following table summarizes the key search features available in [{{{esql}}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced, organized chronologically by release. +The following table summarizes the key search features available in [{{esql}}](/explore-analyze/query-filter/languages/esql.md) and when they were introduced, organized chronologically by release. | Feature | Description | Available since | |---------|-------------|----------------| @@ -33,9 +33,9 @@ The following table summarizes the key search features available in [{{{esql}}}] | [Kibana Query Language](#kql-function) | Use Kibana Query Language with the `KQL` function | 8.18/9.0 | | [Match phrase function](#match_phrase-function) | Perform phrase matching with `MATCH_PHRASE` function | 8.19/9.1 | -## How search works in {{{esql}}} +## How search works in {{esql}} -{{{esql}}} 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. +{{esql}} 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. @@ -53,7 +53,7 @@ The following table summarizes the key search features available in [{{{esql}}}] - Any scenario where you want the "best" matches first - You want to use [analyzers](elasticsearch://reference/elasticsearch/mapping-reference/analyzer.md) or [synonyms](/solutions/search/full-text/search-with-synonyms.md) -{{{esql}}}'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. +{{esql}}'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 [esql-for-search-scoring] @@ -116,14 +116,14 @@ Refer to [hybrid search with semantic_text](hybrid-semantic-text.md) for an exam ### Tutorials and how-to guides [esql-for-search-tutorials] -- [Search and filter with {{{esql}}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{{esql}}}, with concrete examples of the functionalities described in this page +- [Search and filter with {{esql}}](esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}}, with concrete examples of the functionalities described in this page ### Technical reference [esql-for-search-reference] - [Search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md): Complete reference for all search functions -- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search functions in {{{esql}}} +- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md#esql-limitations-full-text-search): Current limitations for search functions in {{esql}} ### Related blog posts [esql-for-search-blogs] -- [{{{esql}}}, you know for Search](https://www.elastic.co/search-labs/blog/esql-introducing-scoring-semantic-search): Introducing scoring and semantic search -- [Introducing full text filtering in {{{esql}}}](https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr): Overview of {{{esql}}}'s text filtering capabilities +- [{{esql}}, you know for Search](https://www.elastic.co/search-labs/blog/esql-introducing-scoring-semantic-search): Introducing scoring and semantic search +- [Introducing full text filtering in {{esql}}](https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr): Overview of {{esql}}'s text filtering capabilities