Consolidates troubleshooting content into the "Returning semantic field embeddings in _source" section by kosabogi · Pull Request #137233 · elastic/elasticsearch

kosabogi · 2025-10-28T08:49:08Z

This PR merges the "Troubleshooting semantic_text fields" section into the "Returning semantic field embeddings in _source" section to reduce duplication and improve clarity.
It also adds an annotated example response that explains key fields (inference_id, model_settings and embeddings) in the _inference_fields object.

Related issue: elastic/docs-content#2955
(The scope of this issue has changed, as per this comment and my discussion with @Mikep86 )

elasticsearchmachine · 2025-10-28T08:49:33Z

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

github-actions · 2025-10-28T08:51:20Z

🔍 Preview links for changed docs

docs/reference/elasticsearch/mapping-reference/semantic-text.md

github-actions · 2025-10-28T08:51:21Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

Mikep86

Looks pretty good overall, thank you for following up on this! I left a couple comments about some minor adjustments we should consider.

docs/reference/elasticsearch/mapping-reference/semantic-text.md

Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co>

docs/reference/elasticsearch/mapping-reference/semantic-text.md

jimczi · 2025-10-31T10:00:53Z

docs/reference/elasticsearch/mapping-reference/semantic-text.md

+  },
+  "fields": [
+    "_inference_fields"
+  ]


Please use the version with exclude_vectors to false, this is the preferred way to retrieve the field.

Thank you for your suggestions, @jimczi!
I deleted the unnecessary "_inference_fields" where we use exclude_vectors.
As Mike suggested in his comment, I created two versions of this: one for 9.0 and 9.1 versions and one for 9.2 since exclude_vectors: false was added only in the 9.2 version.

Can we start with the preferred and current way of doing things? We can document the old way but it should be a small warning section without needing to repeat the entire response (it's the same).

I’ve reordered the sections so that the 9.2 method appears first.
I also added a warning to the 9.0-9.1 method to emphasize that users on 9.2 or later should use the newer approach instead.

I thought it might work better to keep both methods as equivalent sections instead of putting the 9.0-9.1 version in a warning. Since this documentation set covers all versions starting from 9.0, it feels clearer to show both approaches while highlighting which versions they apply to. I labeled the current recommended method as applicable from version 9.2 to make that distinction clear.

Let me know what you think!

Mikep86

The content looks good, thank you for the iterations! I left one comment about mentioning serverless in the applies_to tag.

Tangential to this PR, I think we can make a few changes to Example: Reindex while preserving embeddings to make it clearer:

Use an applies_to tag to indicate that this example only applies to 9.2+ and serverless
Remove the section that uses the fields param. The fields param can't be used during reindexing, so mentioning it as part of reindexing is confusing.

That change could be it's own PR though. WDYT?

docs/reference/elasticsearch/mapping-reference/semantic-text.md

kosabogi · 2025-11-04T11:37:03Z

The content looks good, thank you for the iterations! I left one comment about mentioning serverless in the applies_to tag.

Tangential to this PR, I think we can make a few changes to Example: Reindex while preserving embeddings to make it clearer:

Use an applies_to tag to indicate that this example only applies to 9.2+ and serverless

Remove the section that uses the fields param. The fields param can't be used during reindexing, so mentioning it as part of reindexing is confusing.

That change could be it's own PR though. WDYT?

Thank you, really good catches!
I applied your suggestions in this PR, as I felt it would be confusing without them.

In my latest commit, I made the following changes:

Added an applies-to tag to the Example: Reindex while preserving embeddings section.
Removed the note that mentioned the fields parameter, since we now show the method for retrieving embeddings for earlier versions (pre-9.2) in a dedicated section.
Renamed the Returning semantic field embeddings for 9.0–9.1 section to Returning semantic field embeddings using fields to stay consistent with the Returning semantic field embeddings in source title.
Moved the Returning semantic field embeddings using fields section one level higher. I did this because it makes more sense for it to be a separate section rather than part of Returning semantic field embeddings in source, as it describes a different method.
At the beginning of the Returning semantic field embeddings using fields section, I added a warning to clarify that this applies only to Elasticsearch versions earlier than 9.2, and that users on 9.2+ should refer to the other section.
At the beginning of the Returning semantic field embeddings in source section, I added a note linking to the section that explains the method for earlier versions.

What do you think about it now?

Mikep86

Structure looks good to me, I left a few comments about minor edits

docs/reference/elasticsearch/mapping-reference/semantic-text.md

Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co>

Mikep86

LGTM, thank you for the iterations!

jimczi

Sorry I didn't meant to block the merging with my old request for changes. :LGTM

szabosteve

I left a few comments.

docs/reference/elasticsearch/mapping-reference/semantic-text.md

szabosteve · 2025-11-06T09:40:43Z

docs/reference/elasticsearch/mapping-reference/semantic-text.md

+3. The embeddings generated for this chunk.
+
+## Returning semantic field embeddings using `fields` [return-embeddings-fields]
+


Is there a reason not to add an applies_to tag that lists 9.0 and 9.1 and marks it unavailable from 9.2?

Yes - I didn’t want to mark this as unavailable from 9.2, since it’s not technically unavailable, it’s just not recommended to use.
I thought specifically listing 9.0 and 9.1 might be a bit misleading, as it could imply that this parameter is only available starting from 9.0. But I’m open to adding the 9.0 and 9.1 tags here, I was thinking about that myself too. Do you think it would be better?

Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>

leemthompo

If Jim and Mike are happy, I'm happy 😄 and we'll revisit this page to break it up into logical subpages and cleanup versioning conditionals as much as possible in future work

Thx!

…ld embeddings in _source" section (elastic#137233) * Consolidates the Troubleshooting section * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Test applies switch tabs * Adds version specific examples * Syntax fix * Fixes syntax * Adds separate tabs for each versions * Adds only two version tahs * Deletes tabs, uses section level applies-to instead * Removes response block, adds intros and warning * Reorganizes content, adds applies_to where necessary * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Adds additional information, changes admonition types * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co> * Shorten tab titles --------- Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>

…-json * upstream/main: Mute org.elasticsearch.xpack.inference.action.filter.ShardBulkInferenceActionFilterBasicLicenseIT testLicenseInvalidForInference {p0=false} elastic#137691 Mute org.elasticsearch.xpack.inference.action.filter.ShardBulkInferenceActionFilterBasicLicenseIT testLicenseInvalidForInference {p0=true} elastic#137690 [LTR] Fix feature display order when using explain. (elastic#137671) Remove extra RemoteClusterService instances in unit test (elastic#137647) Fix `ComponentTemplatesFileSettingsIT.testSettingsApplied` (elastic#137669) Consolidates troubleshooting content into the "Returning semantic field embeddings in _source" section (elastic#137233) Update bundled JDK to 25.0.1 (elastic#137640) resolve indices for prefixed _all expressions (elastic#137330) ESQL: Add TopN support for exponential histograms (elastic#137313) allows field caps to be cross project (elastic#137530) ESQL: Add exponential histogram percentile function (elastic#137553) Wait for nodes to have downloaded databases in `GeoIpDownloaderIT` (elastic#137636) Tighten on when THROTTLE decision can be returned (elastic#136794) Mute org.elasticsearch.xpack.esql.qa.single_node.GenerativeMetricsIT test elastic#137655 Add a test for two little known conditional processor paths (elastic#137645) Extract a common ORIGIN constant (elastic#137612) Remove early phase failure in batched (elastic#136889) Returning correct index mode from get data streams api (elastic#137646) [ML] Manage AD results indices (elastic#136065)

…ld embeddings in _source" section (elastic#137233) * Consolidates the Troubleshooting section * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Test applies switch tabs * Adds version specific examples * Syntax fix * Fixes syntax * Adds separate tabs for each versions * Adds only two version tahs * Deletes tabs, uses section level applies-to instead * Removes response block, adds intros and warning * Reorganizes content, adds applies_to where necessary * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> * Adds additional information, changes admonition types * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co> * Shorten tab titles --------- Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co> Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>

Consolidates the Troubleshooting section

3ecd9c7

kosabogi requested a review from Mikep86 October 28, 2025 08:49

kosabogi added >docs General docs changes Team:Docs Meta label for docs team v9.0.0 v9.1.0 v9.2.0 labels Oct 28, 2025

kosabogi changed the title ~~Consolidates troubleshooting content into Returning semantic field embeddings section~~ Oct 28, 2025

elasticsearchmachine added the v9.3.0 label Oct 28, 2025

Merge branch 'main' into semantic-blend-troubleshooting-section

6b49e51

Merge branch 'main' into semantic-blend-troubleshooting-section

7dae585

kosabogi requested review from a team and removed request for a team October 29, 2025 15:52

Mikep86 reviewed Oct 29, 2025

View reviewed changes

docs/reference/elasticsearch/mapping-reference/semantic-text.md Outdated Show resolved Hide resolved

docs/reference/elasticsearch/mapping-reference/semantic-text.md Outdated Show resolved Hide resolved

kosabogi and others added 2 commits October 30, 2025 11:20

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

fb44113

Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co>

Test applies switch tabs

96d7183

Mikep86 reviewed Oct 30, 2025

View reviewed changes

docs/reference/elasticsearch/mapping-reference/semantic-text.md Outdated Show resolved Hide resolved

kosabogi and others added 4 commits October 31, 2025 10:18

Adds version specific examples

fd7eb83

Syntax fix

3767283

Fixes syntax

d26917b

Merge branch 'main' into semantic-blend-troubleshooting-section

7fbdb71

jimczi requested changes Oct 31, 2025

View reviewed changes

Adds separate tabs for each versions

fc06c3f

kosabogi marked this pull request as draft October 31, 2025 10:29

kosabogi added 2 commits October 31, 2025 11:40

Adds only two version tahs

4db8fb2

Deletes tabs, uses section level applies-to instead

e2a1224

kosabogi marked this pull request as ready for review October 31, 2025 11:37

Merge branch 'main' into semantic-blend-troubleshooting-section

cabbfee

kosabogi requested review from Mikep86 and jimczi October 31, 2025 11:37

Removes response block, adds intros and warning

4ff57b9

Mikep86 approved these changes Nov 3, 2025

View reviewed changes

docs/reference/elasticsearch/mapping-reference/semantic-text.md Show resolved Hide resolved

Reorganizes content, adds applies_to where necessary

5be7634

kosabogi requested a review from Mikep86 November 4, 2025 14:31

Merge branch 'main' into semantic-blend-troubleshooting-section

60b518d

Mikep86 reviewed Nov 4, 2025

View reviewed changes

kosabogi and others added 2 commits November 5, 2025 09:00

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

037bbf7

Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co>

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

576d820

Co-authored-by: Mike Pellegrini <mike.pellegrini@elastic.co>

kosabogi requested a review from Mikep86 November 5, 2025 08:54

Adds additional information, changes admonition types

457e7b8

Mikep86 approved these changes Nov 5, 2025

View reviewed changes

jimczi approved these changes Nov 5, 2025

View reviewed changes

kosabogi requested a review from a team November 6, 2025 08:58

szabosteve reviewed Nov 6, 2025

View reviewed changes

Update docs/reference/elasticsearch/mapping-reference/semantic-text.md

511f019

Co-authored-by: István Zoltán Szabó <istvan.szabo@elastic.co>

kosabogi requested a review from szabosteve November 6, 2025 10:03

kosabogi and others added 2 commits November 6, 2025 11:18

Shorten tab titles

a07dcb1

Merge branch 'main' into semantic-blend-troubleshooting-section

6618e0d

leemthompo approved these changes Nov 6, 2025

View reviewed changes

kosabogi merged commit 02ea910 into elastic:main Nov 6, 2025
11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consolidates troubleshooting content into the "Returning semantic field embeddings in _source" section#137233

Consolidates troubleshooting content into the "Returning semantic field embeddings in _source" section#137233
kosabogi merged 22 commits intoelastic:mainfrom
kosabogi:semantic-blend-troubleshooting-section

kosabogi commented Oct 28, 2025

elasticsearchmachine commented Oct 28, 2025

github-actions bot commented Oct 28, 2025 •

edited

Loading

github-actions bot commented Oct 28, 2025

When to use applies_to tags:

What NOT to do:

Mikep86 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jimczi Oct 31, 2025

kosabogi Oct 31, 2025

jimczi Oct 31, 2025

kosabogi Nov 3, 2025 •

edited

Loading

Mikep86 left a comment

Uh oh!

kosabogi commented Nov 4, 2025

Mikep86 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Mikep86 left a comment

jimczi left a comment

szabosteve left a comment

Uh oh!

szabosteve Nov 6, 2025

kosabogi Nov 6, 2025

leemthompo left a comment •

edited

Loading

Uh oh!

Labels

6 participants

		3. The embeddings generated for this chunk.

		## Returning semantic field embeddings using `fields` [return-embeddings-fields]

Conversation

kosabogi commented Oct 28, 2025

elasticsearchmachine commented Oct 28, 2025

github-actions bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

github-actions bot commented Oct 28, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Mikep86 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jimczi Oct 31, 2025

Choose a reason for hiding this comment

kosabogi Oct 31, 2025

Choose a reason for hiding this comment

jimczi Oct 31, 2025

Choose a reason for hiding this comment

kosabogi Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Mikep86 left a comment

Choose a reason for hiding this comment

Uh oh!

kosabogi commented Nov 4, 2025

Mikep86 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Mikep86 left a comment

Choose a reason for hiding this comment

jimczi left a comment

Choose a reason for hiding this comment

szabosteve left a comment

Choose a reason for hiding this comment

Uh oh!

szabosteve Nov 6, 2025

Choose a reason for hiding this comment

kosabogi Nov 6, 2025

Choose a reason for hiding this comment

leemthompo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Labels

6 participants

github-actions bot commented Oct 28, 2025 •

edited

Loading

kosabogi Nov 3, 2025 •

edited

Loading

leemthompo left a comment •

edited

Loading