Clarify highlighting docs for semantic_text and interacting with chunks

[kderusso]

We ran into a confusing use case with the semantic highlighter.

PUT my-test-index
{
  "mappings": {
    "properties": {
      "text": {
        "type": "semantic_text"
      }
    }
  }
}

PUT my-test-index/_doc/1
{
  "text": [
    "puggles are pugs and beagles",
    "chiweenies are chihuahuas and dachshunds"
  ]
}

GET my-test-index/_search
{
  "query": {
    "match_all": {}
  },
  "highlight": {
    "fields": {
      "text": {
        "number_of_fragments": 1
      }
    }
  }
}

With the above search, the expectation was that the first snippet would be returned as order was not specified, but in fact the second snippet was returned. This is because we had only asked for one snippet, so only the top scoring snippet was returned.

This clarifies the documentation to show an alternate way to get semantic highlighter chunks, in the order in which they appear in the document:

GET my-test-index/_search
{
  "query": {
    "match_all": {}
  },
  "highlight": {
    "fields": {
      "text": {
        "number_of_fragments": 1
      }
    },
    "highlight_query": {
      "match": {
        "text": "chihuahua"
      }
    }
  }
}

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticsearchmachine]

Pinging @elastic/search-eng (Team:SearchOrg)

[elasticsearchmachine]

Pinging @elastic/search-relevance (Team:Search - Relevance)

[kderusso]

@Samiul-TheSoccerFan what version should this be tagged with?

[Samiul-TheSoccerFan]

It was backported all the way to 8.18 and 9.0. If you are looking for specific versions, I would say from 8.18.4 and 9.0.4.

[github-actions]

🔍 Preview links for changed docs

• docs/reference/elasticsearch/mapping-reference/semantic-text.md
• docs/reference/elasticsearch/rest-apis/highlighting.md

[Mikep86]

Thanks for the quick turnaround on this, and adding match_all at the same time!

[Mikep86]

Should we call out adjusting number_of_fragments here to a larger number to get all chunks in a doc, and how that will be variable?

[kderusso]

Updated in 8cae0f6 LMKWYT

[Mikep86]

LGTM!

[Mikep86]

Nice light-touch change 👍

[Samiul-TheSoccerFan]

LGTM

[elasticsearchmachine]

💔 Backport failed

Status	Branch	Result
❌	8.18	Commit could not be cherrypicked due to conflicts
✅	9.1
❌	8.19	Commit could not be cherrypicked due to conflicts
❌	9.0	Commit could not be cherrypicked due to conflicts

You can use sqren/backport to manually backport by running backport --upstream elastic/elasticsearch --pr 131871

[kderusso]

💔 Some backports could not be created

Status	Branch	Result
✅	9.0
❌	8.19	Conflict resolution was aborted by the user
❌	8.18	Conflict resolution was aborted by the user

Manual backport

To create the backport manually run:

backport --pr 131871

Questions ?

Please refer to the Backport tool documentation

[kderusso]

Removed backport labels for 8.18 and 8.19 - Markdown doesn't exist there.