Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kosabogi merged 22 commits into from
Nov 6, 2025
Merged

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

Changes from 5 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
3ecd9c7
Consolidates the Troubleshooting section
kosabogi Oct 28, 2025
6b49e51
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Oct 28, 2025
7dae585
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Oct 29, 2025
fb44113
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Oct 30, 2025
96d7183
Test applies switch tabs
kosabogi Oct 30, 2025
fd7eb83
Adds version specific examples
kosabogi Oct 31, 2025
3767283
Syntax fix
kosabogi Oct 31, 2025
d26917b
Fixes syntax
kosabogi Oct 31, 2025
7fbdb71
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Oct 31, 2025
fc06c3f
Adds separate tabs for each versions
kosabogi Oct 31, 2025
4db8fb2
Adds only two version tahs
kosabogi Oct 31, 2025
e2a1224
Deletes tabs, uses section level applies-to instead
kosabogi Oct 31, 2025
cabbfee
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Oct 31, 2025
4ff57b9
Removes response block, adds intros and warning
kosabogi Nov 3, 2025
5be7634
Reorganizes content, adds applies_to where necessary
kosabogi Nov 4, 2025
60b518d
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Nov 4, 2025
037bbf7
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Nov 5, 2025
576d820
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Nov 5, 2025
457e7b8
Adds additional information, changes admonition types
kosabogi Nov 5, 2025
511f019
Update docs/reference/elasticsearch/mapping-reference/semantic-text.md
kosabogi Nov 6, 2025
a07dcb1
Shorten tab titles
kosabogi Nov 6, 2025
6618e0d
Merge branch 'main' into semantic-blend-troubleshooting-section
kosabogi Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 107 additions & 30 deletions docs/reference/elasticsearch/mapping-reference/semantic-text.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,7 @@ serverless: ga

By default, the embeddings generated for `semantic_text` fields are stored internally and **not included in `_source`** when retrieving documents.

To include the full inference fields, including their embeddings, in `_source`, set the `_source.exclude_vectors` option to `false`.
To include the full {{infer}} fields, including their embeddings, in `_source`, set the `_source.exclude_vectors` option to `false`.
This works with the
[Get](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-get),
[Search](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search),
Expand All @@ -468,11 +468,12 @@ POST my-index/_search
}
}
```
% TEST[skip:Requires inference endpoint]
% TEST[skip:Requires {{infer}} endpoint]

The embeddings will appear under `_inference_fields` in `_source`.

**Use cases**

Including embeddings in `_source` is useful when you want to:

* Reindex documents into another index **with the same `inference_id`** without re-running inference.
Expand All @@ -495,7 +496,7 @@ POST _reindex
}
}
```
% TEST[skip:Requires inference endpoint]
% TEST[skip:Requires {{infer}} endpoint]

1. Sends the source documents with their stored embeddings to the destination index.

Expand All @@ -505,7 +506,7 @@ the documents will **fail the reindex task**.
Matching `inference_id` values are required to reuse the existing embeddings.
::::

This allows documents to be re-indexed without triggering inference again, **as long as the target `semantic_text` field uses the same `inference_id` as the source**.
This allows documents to be re-indexed without triggering {{infer}} again, **as long as the target `semantic_text` field uses the same `inference_id` as the source**.

::::{note}
**For versions prior to 9.2.0**
Expand All @@ -514,7 +515,7 @@ Older versions do not support the `exclude_vectors` option to retrieve the embed
To return the `_inference_fields`, use the `fields` option in a search request instead:

```console
POST test-index/_search
POST my-index/_search
{
"query": {
"match": {
Expand All @@ -526,12 +527,112 @@ POST test-index/_search
]
}
```
% TEST[skip:Requires inference endpoint]
% TEST[skip:Requires {{infer}} endpoint]

This returns the chunked embeddings used for semantic search under `_inference_fields` in `_source`.
Note that the `fields` option is **not** available for the Reindex API.
::::

### Example: Troubleshooting semantic_text fields [troubleshooting-semantic-text-fields]

::::{applies-switch}
:::{applies-item} { "stack": "preview 9.0" }
Content for 9.0 version
:::
:::{applies-item} { "stack": "ga 9.1" }
Content for 9.1 version
:::
::::

::::{applies-switch}
:::{applies-item} stack: preview 9.0
Other content for 9.0 version
:::
:::{applies-item} stack: ga 9.1
Other content for 9.1 version
:::
::::

If you want to verify that your embeddings look correct, you can view the
{{infer}} data that `semantic_text` typically hides using `fields`.

```console
POST my-index/_search
{
"query": {
"match": {
"my_semantic_field": "Which country is Paris in?"
}
},
"fields": [
"_inference_fields"
]
Copy link
Contributor

@jimczi jimczi Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@kosabogi kosabogi Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@jimczi jimczi Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor Author

@kosabogi kosabogi Nov 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

}
```
% TEST[skip:Requires {{infer}} endpoint]

This will return verbose chunked embeddings content that is used to perform
semantic search for `semantic_text` fields.

```console-response
{
"took": 179,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": { "value": 1, "relation": "eq" },
"max_score": 16.532316,
"hits": [
{
"_index": "test-index",
"_id": "1",
"_score": 16.532316,
"_source": {
"my_semantic_field": "Paris is the capital of France.",
"_inference_fields": {
"my_semantic_field": {
"inference": {
"inference_id": ".elser-2-elasticsearch", <1>
"model_settings": { <2>
"service": "elasticsearch",
"task_type": "sparse_embedding"
},
"chunks": {
"my_semantic_field": [
{
"start_offset": 0,
"end_offset": 31,
"embeddings": { <3>
"paris": 2.5234375,
"france": 2.0,
"capital": 2.1328125,
"city": 1.265625,
"country": 0.59765625,
...
}
}
]
}
}
}
}
}
}
]
}
}
```
% TEST[skip:Requires {{infer}} endpoint]
1. The {{infer}} endpoint used to generate embeddings.
2. Lists details about the model used to generate embeddings, such as the service name and task type.
3. The embeddings generated for this chunk.


## Customizing `semantic_text` indexing [custom-indexing]

`semantic_text` uses defaults for indexing data based on the {{infer}} endpoint
Expand Down Expand Up @@ -656,30 +757,6 @@ You can query `semantic_text` fields using the following query types:

- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md): We don't recommend this legacy query type for _new_ projects, because the alternatives in this list enable more flexibility and customization. The `semantic` query remains available to support existing implementations.


## Troubleshooting semantic_text fields [troubleshooting-semantic-text-fields]

If you want to verify that your embeddings look correct, you can view the
inference data that `semantic_text` typically hides using `fields`.

```console
POST test-index/_search
{
"query": {
"match": {
"my_semantic_field": "Which country is Paris in?"
}
},
"fields": [
"_inference_fields"
]
}
```
% TEST[skip:Requires inference endpoint]

This will return verbose chunked embeddings content that is used to perform
semantic search for `semantic_text` fields.

### Document count discrepancy in `_cat/indices`

When an index contains a `semantic_text` field, the `docs.count` value returned by the [`_cat/indices`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-indices) API may be higher than the number of documents you indexed.
Expand Down