Browse Source

[DOCS] Update esql-for-search for 8.19 (#131834)

8.19 equivalent of https://github.com/elastic/docs-content/pull/1797
Liam Thompson 2 months ago
parent
commit
2f81cef302

+ 77 - 129
docs/reference/esql/esql-for-search.asciidoc

@@ -1,212 +1,160 @@
 [[esql-for-search]]
 === Using {esql} for search
 
-preview::[]
-
 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 <<esql-search-tutorial>>.
+For a hands-on tutorial check out <<esql-search-tutorial>>.
 ====
 
-The following table summarizes the key search features available in {esql} and when they were introduced.
+[[esql-search-quick-reference]]
+==== {esql} search quick reference
+
+The following table summarizes the key search features available in {esql} and when they were introduced, organized chronologically by release.
 
-[cols="1,1,2", options="header"]
+[cols="1,2,1", options="header"]
 |===
-|Feature |Available since |Description
+|Feature |Description |Available since
 
-|<<esql-search-functions,Full text search functions>>
+|<<esql-for-search-match-function-operator,Match function/operator>>
+|Perform basic text searches with `MATCH` function or match operator (`:`)
 |8.17
-|Perform basic text searches with <<esql-match, match function>> and <<esql-search-operators,match operator (`:`)>>
 
 |<<esql-for-search-query-string,Query string function>>
+|Execute complex queries with `QSTR` using Query String syntax
 |8.17
-|Execute complex queries with <<esql-qstr,`qstr`>> using Query String syntax
 
 |<<esql-for-search-scoring,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
-
-|<<esql-for-search-kql,Kibana Query Language>>
 |8.18/9.0
-|Use Kibana Query Language with <<esql-kql,`kql`>> function
 
 |<<esql-for-search-semantic,Semantic search>>
-|8.18/9.0
 |Perform semantic searches on `semantic_text` field types
+|8.18/9.0
 
 |<<esql-for-search-hybrid,Hybrid search>>
-|8.18/9.0
 |Combine lexical and semantic search approaches with custom weights
+|8.18/9.0
+
+|<<esql-for-search-kql,Kibana Query Language>>
+|Use Kibana Query Language with the `KQL` function
+|8.18/9.0
+
+|<<esql-match-phrase-function,Match phrase function>>
+|Perform phrase matching with `MATCH_PHRASE` function
+|8.19/9.1
 |===
 
-[[esql-filtering-vs-searching]]
-==== Filtering vs. searching
+[[how-search-works-in-esql]]
+==== How search works in {esql}
 
-{esql} can be used for both simple filtering and relevance-based searching:
+{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 non-matching documents without calculating relevance scores
-* **Searching** both filters documents and ranks them by how well they match the query
+**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.
 
-Note that filtering is faster than searching, because it doesn't require score calculations.
+**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.
 
-[[esql-for-search-scoring]]
-===== Relevance scoring
 
-To get the most relevant results first, you need to use `METADATA _score` and sort by score. For example:
 
-[source,esql]
-----
-FROM books METADATA _score
-| WHERE match(title, "Shakespeare") OR match(plot, "Shakespeare")
-| SORT _score DESC
-----
+**When to choose filtering:**
 
-[[esql-for-search-how-scoring-works]]
-===== How `_score` works
+* 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 working with relevance scoring in ES|QL:
+**When to choose searching:**
 
-* 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.
+* 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 <<analysis,analyzers>> or <<search-with-synonyms,synonyms>>
 
-[[esql-for-search-full-text]]
-==== Full text search
+{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-for-search-match-function-operator]]
-===== Match function and operator
+[[esql-for-search-scoring]]
+===== Relevance scoring
 
-ES|QL offers two syntax options for `match`, which replicate the functionality of <<query-dsl-match-query, `match`>> queries in Query DSL.
+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.
 
-Use the compact operator syntax (`:`) for simple text matching with default parameters.
+**Without `METADATA _score`**: All operations are filtering-only, even `MATCH`, `QSTR`, and `KQL` functions. Documents either match or don't match - no ranking occurs.
 
-[source,esql]
-----
-FROM logs | WHERE match(message, "connection error")
-----
+**With `METADATA _score`**: <<esql-search-functions,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.
 
-Use the `match()` function syntax when you need to pass additional parameters:
+This gives you full control over when to use fast filtering versus slower but more powerful relevance-based searching.
 
-[source,esql]
-----
-FROM products | WHERE match(name, "laptop", { "boost": 2.0 })
-----
+[[search-functions]]
+==== Search functions
 
-These full-text functions address several key limitations that existed for text filtering in {esql}:
+The following functions provide text-based search capabilities in {esql} with different levels of precision and control.
 
-* 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
+[[esql-for-search-match-function-operator]]
+===== `MATCH` function and operator
 
-Refer to this blog for more context: https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr[Introducing full text filtering in ES|QL].
 
-[TIP]
-====
-See <<match-field-params,Match field parameters>> for more advanced options using match. 
-====
+{esql} offers two syntax options for match, which replicate the functionality of <<query-dsl-match-query, `match`>> queries in Query DSL.
 
-[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 <<esql-for-search-scoring,Relevance scoring>> for more information.
-====
+* Use the compact <<esql-search-operators,match operator (:)>> for simple text matching with default parameters.
+* Use the <<esql-match,MATCH function syntax>> for more control over the query, such as specifying analyzers, fuzziness, and other parameters.
 
-[[esql-for-search-query-string]]
-===== Query string function (`QSTR`)
+Refer to the <<esql-search-tutorial,tutorial>> for examples of both syntaxes.
+
+[[esql-match-phrase-function]]
+===== `MATCH_PHRASE` function
 
-The <<esql-qstr,`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.
+Use the <<esql-match_phrase,`MATCH_PHRASE` function>> to perform a `match_phrase` query on the specified field. This is equivalent to using the <<query-dsl-match-query-phrase,match_phrase query>> in Query DSL.
 
-[source,esql]
-----
-FROM articles METADATA _score
-| WHERE QSTR("(new york city) OR (big apple)")
-| SORT _score DESC
-| LIMIT 10
-----
+For exact phrase matching rather than individual word matching, use `MATCH_PHRASE`.
+
+[[esql-for-search-query-string]]
+===== Query string (`QSTR`) function
+
+The <<esql-qstr,`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-query, Query DSL `query_string` docs>>.
 
 [[esql-for-search-kql]]
-===== Kibana Query Language function (`KQL`)
+===== `KQL` function
 
-Use the <<esql-kql,KQL function>> to use the {kibana-ref}/kuery-query.html[Kibana Query Language] in your ES|QL queries:
+Use the <<esql-kql,KQL function>> to use the {kibana-ref}/kuery-query.html[Kibana Query Language] in your {esql} queries.
 
-[source,esql]
-----
-FROM logs*
-| WHERE KQL("http.request.method:GET AND agent.type:filebeat")
-----
+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.
 
-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.
+[[advanced-search-capabilities]]
+==== Advanced search capabilities
 
 [[esql-for-search-semantic]]
-==== Semantic search
-
-You can perform semantic searches over <<semantic-text, `semantic_text`>> field types using the same match syntax as full-text search.
-
-This example uses the match operator `:`:
+===== Semantic search
 
-[source,esql]
-----
-FROM articles METADATA _score
-| WHERE semantic_content:"What are the impacts of climate change on agriculture?"
-| SORT _score DESC
-----
+<<semantic-search,Semantic search>> leverages machine learning models to understand the meaning of text, enabling more accurate and context-aware search results.
 
-This example uses the match function:
+In {esql}, you can perform semantic searches on <<semantic-text, `semantic_text`>> field types using the same match syntax as full-text search.
 
-[source,esql]
-----
-FROM articles METADATA _score
-| WHERE match(semantic_content, "What are the impacts of climate change on agriculture?")
-| SORT _score DESC
-----
+Refer to <<semantic-search-semantic-text,semantic search with semantic_text>> for an example or follow the <<esql-search-tutorial,tutorial>>.
 
 [[esql-for-search-hybrid]]
-==== Hybrid search
-
-Combine traditional and semantic search with custom weights:
-
-[source,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
-----
+===== Hybrid search
 
-[[esql-for-search-limitations]]
-==== Limitations
+Hybrid search combines lexical and semantic search with custom weights to leverage both exact keyword matching and semantic understanding.
 
-Refer to <<esql-limitations-full-text-search, {esql} limitations>> for a list of known limitations.
+Refer to <<semantic-text-hybrid-search,hybrid search with semantic_text>> for an example or follow the <<esql-search-tutorial,tutorial>>.
 
 [[esql-for-search-next-steps]]
 ==== Next steps
 
+
 [[esql-for-search-tutorials]]
 ===== Tutorials and how-to guides
 
-* <<esql-search-tutorial>>: Hands-on tutorial for getting started with search tools in {esql}
-* <<semantic-search-semantic-text>>: Learn how to use the `semantic_text` field type
+* <<esql-search-tutorial>>: Hands-on tutorial for getting started with search tools in {esql}, with concrete examples of the functionalities described in this page
+
 
 [[esql-for-search-reference]]
 ===== Technical reference
 
 * <<esql-search-functions>>: Complete reference for all search functions
-* <<esql-limitations-full-text-search, Limitations>>: Current limitations for search in ES|QL
-
-[[esql-for-search-concepts]]
-===== Background concepts
-
-* <<analysis>>: Learn how text is processed for full-text search
-* <<semantic-search>>: Get an overview of semantic search in {es}
-* <<query-filter-context>>: Understand the difference between query and filter contexts in {es}
+* <<esql-limitations-full-text-search, Limitations>>: Current limitations for search functions in {esql}
 
 [[esql-for-search-blogs]]
 ===== Related blog posts

+ 195 - 100
docs/reference/quickstart/esql-search-tutorial.asciidoc

@@ -19,7 +19,7 @@ In this scenario, we're implementing search for a cooking blog. The blog contain
 [[esql-search-tutorial-requirements]]
 === Requirements
 
-You'll need a running {es} cluster, together with {kib} to use the Dev Tools API Console. Refer to <<elasticsearch-intro-deploy,choose your deployment type>> for deployment options.
+You need a running {es} cluster, together with {kib} to use the Dev Tools API Console. Refer to <<elasticsearch-intro-deploy,choose your deployment type>> for deployment options.
 
 Want to get started quickly? Run the following command in your terminal to set up a <<run-elasticsearch-locally,single-node local cluster in Docker>>:
 
@@ -33,7 +33,7 @@ curl -fsSL https://elastic.co/start-local | sh
 [[esql-search-tutorial-running-esql-queries]]
 === 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:
 
 [source,esql]
 ----
@@ -42,7 +42,7 @@ FROM cooking_blog
 | LIMIT 1000
 ----
 
-If you want to run these queries in the <<esql-kibana-console,Dev Tools Console>>, you'll need to use the following syntax:
+If you want to run these queries in the <<esql-kibana-console,Dev Tools Console>>, you need to use the following syntax:
 
 [source,js]
 ----
@@ -162,80 +162,126 @@ 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]]
 [discrete]
-=== 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 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 <<esql-match,match function>> syntax: `match(field, "search terms")`
 2. Compact syntax using the <<esql-search-operators,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 use the compact syntax in most examples for brevity.
 
 Refer to the <<esql-match,match function>> reference docs for advanced parameters available with the function syntax.
-=====
 
 [discrete]
-[[esql-search-tutorial-basic-full-text-query]]
-==== Basic full-text query
+[[esql-search-tutorial-make-first-search]]
+==== 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:
 
 [source,esql]
 ----
-FROM cooking_blog <1>
-| WHERE description:"fluffy pancakes" <2>
-| LIMIT 1000 <3>
+FROM cooking_blog
+| WHERE description:"fluffy pancakes"
+| LIMIT 1000
 ----
-<1> Specify the index to search
-<2> Full-text search with OR logic by default
-<3> Return up to 1000 results
 
-[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 matches 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.
+[discrete]
+[[esql-search-tutorial-control-result-fields]]
+==== 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:
 
 [source,esql]
 ----
 FROM cooking_blog
 | WHERE description:"fluffy pancakes"
-| KEEP title, description, rating <1>
+| KEEP title, description, rating
 | LIMIT 1000
 ----
-<1> Select only specific fields to include in response
+
+This helps reduce the amount of data returned and focuses on the information you need.
+
+[discrete]
+[[esql-search-tutorial-relevance-scoring-basics]]
+==== Understand relevance scoring
+
+Search results can be ranked by how well they match your query. To calculate and use relevance scores, you need to explicitly request the `_score` metadata:
+
+[source,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.
 =====
 
+[discrete]
+[[esql-search-tutorial-exact-matches-basics]]
+==== Find exact matches
+
+Sometimes you need exact matches rather than full-text search. Use the `.keyword` field for case-sensitive exact matching:
+
+[source,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.
+
+[discrete]
+[[step-4-search-precision-control]]
+=== Step 4: Search precision control
+
+Now that you understand basic searching, let's explore how to control the precision of your text matches.
+
 [discrete]
 [[esql-search-tutorial-require-all-terms]]
-==== Require all terms in a match query
+==== 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:
 
 [source,esql]
 ----
 FROM cooking_blog
-| WHERE match(description, "fluffy pancakes", {"operator": "AND"}) <1>
+| WHERE match(description, "fluffy pancakes", {"operator": "AND"})
 | LIMIT 1000
 ----
-<1> Require ALL terms to match
 
 This stricter search returns *zero hits* on our sample data, as no document contains both "fluffy" and "pancakes" in the description.
 
+[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.
+=====
+
 [discrete]
 [[esql-search-tutorial-minimum-terms]]
-==== Specify a minimum number of terms to match
+==== 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:
 
@@ -248,9 +294,25 @@ FROM cooking_blog
 
 This query searches the title field to match at least 2 of the 3 terms: "fluffy", "pancakes", or "breakfast".
 
+[discrete]
+[[esql-search-tutorial-match-phrase]]
+==== Search for exact phrases
+
+When you need to find documents containing an exact sequence of words, use the `MATCH_PHRASE` function:
+
+[source,esql]
+----
+FROM cooking_blog
+| WHERE MATCH_PHRASE(description, "rich and creamy")
+| KEEP title, description
+| LIMIT 1000
+----
+
+This query only matches documents where the words "rich and creamy" appear exactly in that order in the description field.
+
 [discrete]
 [[esql-search-tutorial-semantic-search]]
-=== Step 4: Semantic search and hybrid search
+=== Step 5: Semantic search and hybrid search
 
 [discrete]
 [[esql-search-tutorial-index-semantic-content]]
@@ -322,11 +384,43 @@ FROM cooking_blog METADATA _score
 | LIMIT 5
 ----
 
+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-complex-search-solutions>>.
+
+[discrete]
+[[step-6-advanced-search-features]]
+=== Step 6: Advanced search features
+
+Once you're comfortable with basic search precision, these advanced features give you powerful search capabilities.
+
+[discrete]
+[[esql-search-tutorial-query-string]]
+==== 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:
+
+[source,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)")`
+
 [discrete]
 [[esql-search-tutorial-search-across-fields]]
-=== Step 5: Search across multiple fields at once
+==== 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:
 
 [source,esql]
 ----
@@ -337,130 +431,131 @@ 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:
+[discrete]
+[[esql-search-tutorial-weight-fields]]
+==== 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:
 
 [source,esql]
 ----
-FROM cooking_blog METADATA _score <1>
-| WHERE match(title, "vegetarian curry", {"boost": 2.0}) <2>
+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 <3>
-| SORT _score DESC <4>
+| KEEP title, description, tags, _score
+| SORT _score DESC
 | LIMIT 1000
 ----
-<1> Request _score metadata for relevance-based results
-<2> Title matches are twice as important
-<3> Include relevance score in results
-<4> You must explicitly sort by `_score` to see relevance-based results
-
-[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`.
-=====
 
 [discrete]
-[[esql-search-tutorial-filter-exact-matches]]
-=== Step 6: Filter and find exact matches
+[[step-7-filtering-exact-matching]]
+=== 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.
 
+[discrete]
+[[esql-search-tutorial-filter-category]]
+==== Basic filtering by category
+
 [source,esql]
 ----
 FROM cooking_blog
-| WHERE category.keyword == "Breakfast" <1>
+| WHERE category.keyword == "Breakfast"  # Exact match using keyword field
 | KEEP title, author, rating, tags
 | SORT rating DESC
 | LIMIT 1000
 ----
-<1> Exact match using keyword field (case-sensitive)
 
 Note the use of `category.keyword` here. This refers to the <<keyword,`keyword`>> multi-field of the `category` field, ensuring an exact, case-sensitive match.
 
 [discrete]
 [[esql-search-tutorial-date-range]]
-==== Search for posts within a date range
+==== Date range filtering
 
 Often users want to find content published within a specific time frame:
 
 [source,esql]
 ----
 FROM cooking_blog
-| WHERE date >= "2023-05-01" AND date <= "2023-05-31" <1>
+| WHERE date >= "2023-05-01" AND date <= "2023-05-31"
 | KEEP title, author, date, rating
 | LIMIT 1000
 ----
-<1> Inclusive date range filter
 
 [discrete]
-[[esql-search-tutorial-exact-matches]]
-==== Find exact matches
+[[esql-search-tutorial-numerical-range]]
+==== 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:
 
 [source,esql]
 ----
 FROM cooking_blog
-| WHERE author.keyword == "Maria Rodriguez" <1>
+| WHERE rating >= 4.5  # Only highly-rated recipes
 | KEEP title, author, rating, tags
 | SORT rating DESC
 | LIMIT 1000
 ----
-<1> Exact match on author
 
-Like the `term` query in Query DSL, this has zero flexibility and is case-sensitive.
+[discrete]
+[[esql-search-tutorial-exact-author]]
+==== Exact author matching
+
+Find recipes by a specific author:
+
+[source,esql]
+----
+FROM cooking_blog
+| WHERE author.keyword == "Maria Rodriguez"
+| KEEP title, author, rating, tags
+| SORT rating DESC
+| LIMIT 1000
+----
+
+[discrete]
+[[step-8-complex-search-solutions]]
+=== Step 8: Complex search solutions
+
+Real-world search often requires combining multiple types of criteria. This section shows how to build sophisticated search experiences.
 
 [discrete]
 [[esql-search-tutorial-combine-criteria]]
-=== 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:
 
 [source,esql]
 ----
 FROM cooking_blog METADATA _score
-| WHERE rating >= 4.5 <1>
-    AND NOT category.keyword == "Dessert" <2>
-    AND (title:"curry spicy" OR description:"curry spicy") <3>
+| WHERE rating >= 4.5
+    AND NOT category.keyword == "Dessert"
+    AND (title:"curry spicy" OR description:"curry spicy")
 | SORT _score DESC
 | KEEP title, author, rating, tags, description
 | LIMIT 1000
 ----
-<1> Numerical filter
-<2> Exclusion filter
-<3> Full-text search in multiple fields
 
 [discrete]
-[[esql-search-tutorial-relevance-scoring]]
-==== Combine relevance scoring with custom criteria
+[[esql-search-tutorial-advanced-relevance-scoring]]
+==== 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:
 
 [source,esql]
 ----
 FROM cooking_blog METADATA _score
 | WHERE NOT category.keyword == "Dessert"
-| EVAL tags_concat = MV_CONCAT(tags.keyword, ",") <1>
-| WHERE tags_concat LIKE "*vegetarian*" AND rating >= 4.5 <2>
-| WHERE match(title, "curry spicy", {"boost": 2.0}) OR match(description, "curry spicy") <3>
-| EVAL category_boost = CASE(category.keyword == "Main Course", 1.0, 0.0) <4>
-| EVAL date_boost = CASE(DATE_DIFF("month", date, NOW()) <= 1, 0.5, 0.0) <5>
-| EVAL custom_score = _score + category_boost + date_boost <6>
-| WHERE custom_score > 0 <7>
+| EVAL tags_concat = MV_CONCAT(tags.keyword, ",")
+| WHERE tags_concat LIKE "*vegetarian*" AND rating >= 4.5
+| 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)
+| EVAL date_boost = CASE(DATE_DIFF("month", date, NOW()) <= 1, 0.5, 0.0)
+| EVAL custom_score = _score + category_boost + date_boost
+| WHERE custom_score > 0
 | SORT custom_score DESC
 | LIMIT 1000
 ----
-<1> Convert multi-value field to string
-<2> Wildcard pattern matching
-<3> Uses full text functions, will update _score metadata field
-<4> Conditional boost
-<5> Boost recent content
-<6> Combine scores
-<7> Filter based on custom score
 
 [discrete]
 [[esql-search-tutorial-learn-more]]
@@ -472,14 +567,14 @@ FROM cooking_blog METADATA _score
 
 This tutorial introduced the basics of search and filtering in {esql}. Building a real-world search experience requires understanding many more advanced concepts and techniques. Here are some resources once you're ready to dive deeper:
 
-- <<esql-for-search,Search with {esql}>>: Learn about all your options for search use cases with {esql}.
-- <<esql-search-functions,{esql} search functions>>: Explore the full list of search functions available in {esql}.
-- <<semantic-search,Semantic search>>: Understand your various options for semantic search in Elasticsearch.
-  - <<semantic-search-semantic-text,The `semantic_text` workflow>>: Learn how to use the `semantic_text` field type for semantic search. This is the recommended approach for most users looking to perform semantic search in {es}, because it abstracts away the complexity of setting up inference endpoints and models.
+* <<esql-for-search,Search with {esql}>>: Learn about all your options for search use cases with {esql}.
+* <<esql-search-functions,{esql} search functions>>: Explore the full list of search functions available in {esql}.
+* <<semantic-search,Semantic search>>: Understand your various options for semantic search in Elasticsearch.
+** <<semantic-search-semantic-text,The `semantic_text` workflow>>: Learn how to use the `semantic_text` field type for semantic search. This is the recommended approach for most users looking to perform semantic search in {es}, because it abstracts away the complexity of setting up inference endpoints and models.
 
 [discrete]
 [[esql-search-tutorial-blog-posts]]
 ==== Related blog posts
 
-// TODO [[uncomment once blog is live]] - https://www.elastic.co/blog/esql-you-know-for-search-scoring-semantic-search[Introducing scoring and semantic searchin {esql}]: 
-- https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr[Introducing full text filtering in ES|QL]
+* https://www.elastic.co/search-labs/blog/esql-introducing-scoring-semantic-search[ES|QL, you know for Search]
+* https://www.elastic.co/search-labs/blog/filtering-in-esql-full-text-search-match-qstr[Introducing full text filtering in ES|QL]