From 841f7df9f7c469b79a906371655827b0a7321fb3 Mon Sep 17 00:00:00 2001
From: Kathleen DeRusso <kathleen.derusso@elastic.co>
Date: Tue, 29 Jul 2025 08:05:28 -0400
Subject: [PATCH] Clarify highlighting docs for semantic_text and interacting
 with chunks (#131871)

(cherry picked from commit b3510c18e0966262c7246b8b76cfeac927e068ec)
---
 .../mapping-reference/semantic-text.md        | 28 +++++++++++++++++--
 .../elasticsearch/rest-apis/highlighting.md   |  2 +-
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md
index 3a761e5bc6ff1..8762f9f78fcbe 100644
--- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md
+++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md
@@ -144,10 +144,34 @@ POST test-index/_search
 ```
 
 1. Specifies the maximum number of fragments to return.
-2. Sorts highlighted fragments by score when set to `score`. By default, fragments will be output in the order they appear in the field (order: none).
+2. Sorts the most relevant highlighted fragments by score when set to `score`. By default,
+   fragments will be output in the order they appear in the field (order: none).
 
+To use the `semantic` highlighter to view chunks in the order which they were indexed with no scoring,
+use the `match_all` query to retrieve them in the order they appear in the document:
 
-Highlighting is supported on fields other than semantic_text. However, if you want to restrict highlighting to the semantic highlighter and return no fragments when the field is not of type semantic_text, you can explicitly enforce the `semantic` highlighter in the query:
+```console
+POST test-index/_search
+{
+    "query": {
+        "match_all": {}
+    },
+    "highlight": {
+        "fields": {
+            "my_semantic_field": {
+                "number_of_fragments": 5  <1>
+            }
+        }
+    }
+}
+```
+
+1. This will return the first 5 chunks, set this number higher to retrieve more chunks.
+
+Highlighting is supported on fields other than semantic_text. However, if you
+want to restrict highlighting to the semantic highlighter and return no
+fragments when the field is not of type semantic_text, you can explicitly
+enforce the `semantic` highlighter in the query:
 
 ```console
 PUT test-index
diff --git a/docs/reference/elasticsearch/rest-apis/highlighting.md b/docs/reference/elasticsearch/rest-apis/highlighting.md
index 93f58eeb6f14e..bbebb8202f506 100644
--- a/docs/reference/elasticsearch/rest-apis/highlighting.md
+++ b/docs/reference/elasticsearch/rest-apis/highlighting.md
@@ -7,7 +7,7 @@ applies_to:
 
 # Highlighting [highlighting]
 
-Highlighters enable you to get highlighted snippets from one or more fields in your search results so you can show users where the query matches are. When you request highlights, the response contains an additional `highlight` element for each search hit that includes the highlighted fields and the highlighted fragments.
+Highlighters enable you to retrieve the best-matching highlighted snippets from one or more fields in your search results so you can show users where the query matches are. When you request highlights, the response contains an additional `highlight` element for each search hit that includes the highlighted fields and the highlighted fragments.
 
 ::::{note}
 Highlighters don’t reflect the boolean logic of a query when extracting terms to highlight. Thus, for some complex boolean queries (e.g nested boolean queries, queries using `minimum_should_match` etc.), parts of documents may be highlighted that don’t correspond to query matches.