Skip to content

Commit 6ed40ee

Browse files
kosabogileemthompo
kosabogi
and
leemthompo
authored
Restructuring the semantic_text field type page (elastic#138571)
* Restructuring semantic_text field type page (draft) * Restructuring the semantic_text field type page * Fixes link * Adds redirects * Expands intro to semantic_text field type and shorten overview * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <[email protected]> * Apply local fixes from PR review * Adds back heading for customizing semantic_text indexing * Applies suggestions and adds substitutions * Local updates before applying suggestions * Update docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md Co-authored-by: Liam Thompson <[email protected]> * Fixes links. * Fixes link. * Adds a note on the recommendation about dedicated endpoints * Adds dedicated endpoints information for the reference page * Fixes links * Applies suggestions --------- Co-authored-by: Liam Thompson <[email protected]>
1 parent e2aaa5a commit 6ed40ee

File tree

9 files changed

+978
-834
lines changed

9 files changed

+978
-834
lines changed

‎docs/redirects.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,3 +112,17 @@ redirects:
112112
many:
113113
- to: 'reference/elasticsearch/mapping-reference/match-only-text.md'
114114
anchors: { 'match-only-text-field-type', 'match-only-text-params' }
115+
116+
# semantic_text documentation restructuring - anchors moved to new pages
117+
'reference/elasticsearch/mapping-reference/semantic-text.md':
118+
to: 'reference/elasticsearch/mapping-reference/semantic-text.md'
119+
anchors: {} # pass-through unlisted anchors in the `many` ruleset
120+
many:
121+
- to: 'reference/elasticsearch/mapping-reference/semantic-text-setup-configuration.md'
122+
anchors: { 'using-elser-on-eis', 'default-and-preconfigured-endpoints', 'using-custom-endpoint', 'dedicated-endpoints-for-ingestion-and-search', 'configure-inference-endpoints' }
123+
- to: 'reference/elasticsearch/mapping-reference/semantic-text-ingestions.md'
124+
anchors: { 'pre-chunking', 'use-copy-to-with-semantic-text', 'updates-and-partial-updates', 'scripted-updates' }
125+
- to: 'reference/elasticsearch/mapping-reference/semantic-text-search-retrieval.md'
126+
anchors: { 'querying-semantic-text-fields', 'retrieving-indexed-chunks', 'returning-semantic-field-embeddings', 'returning-semantic-field-embeddings-in-_source', 'reindex-while-preserving-embeddings', 'troubleshooting-semantic-text-fields', 'returning-semantic-field-embeddings-using-fields', 'highlighting-fragments', 'cross-cluster-search' }
127+
- to: 'reference/elasticsearch/mapping-reference/semantic-text-reference.md'
128+
anchors: { 'semantic-text-params', 'configuring-inference-endpoints', 'chunking-behavior', 'limitations', 'document-count-discrepancy' }

‎docs/reference/elasticsearch/mapping-reference/semantic-text-how-tos.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
navigation_title: "How-to guides"
3+
mapped_pages:
4+
- https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
5+
applies_to:
6+
stack: ga 9.0
7+
serverless: ga
8+
---
9+
10+
# How-to guides for the `semantic_text` field type
11+
12+
These guides provide procedure descriptions and examples for common tasks when working with `semantic_text` fields:
13+
14+
- [Set up and configure `semantic_text` fields](./semantic-text-setup-configuration.md): Learn how to configure {{infer}} endpoints, including default and preconfigured options, ELSER on EIS, custom endpoints, and dedicated endpoints for ingestion and search operations.
15+
16+
- [Ingest data with `semantic_text` fields](./semantic-text-ingestions.md): Learn how to index pre-chunked content, use `copy_to` and multi-fields to collect values from multiple fields, and perform updates and partial updates to optimize ingestion costs.
17+
18+
- [Search and retrieve `semantic_text` fields](./semantic-text-search-retrieval.md): Learn how to query `semantic_text` fields, retrieve indexed chunks, return field embeddings, and highlight the most relevant fragments from search results.
19+
20+
21+
22+

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

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
navigation_title: "Ingest data"
3+
mapped_pages:
4+
- https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
5+
applies_to:
6+
stack: ga 9.0
7+
serverless: ga
8+
---
9+
10+
# Ingest data with `semantic_text` fields [set-up-configuration-semantic-text]
11+
12+
This page provides instructions for ingesting data into `semantic_text` fields. Learn how to index pre-chunked content, use `copy_to` and multi-fields to collect values from multiple fields, and perform updates and partial updates to optimize ingestion costs.
13+
14+
## Index pre-chunked content [pre-chunking]
15+
```{applies_to}
16+
stack: ga 9.1
17+
```
18+
19+
To index pre-chunked content, provide your text as an array of strings. Each element in the array represents a single chunk that will be sent directly to the {{infer}} service without further chunking.
20+
21+
:::::{stepper}
22+
23+
::::{step} Disable automatic chunking
24+
25+
Disable automatic chunking in your index mapping by setting `chunking_settings.strategy` to `none`:
26+
27+
```console
28+
PUT test-index
29+
{
30+
"mappings": {
31+
"properties": {
32+
"my_semantic_field": {
33+
"type": "semantic_text",
34+
"chunking_settings": {
35+
"strategy": "none" <1>
36+
}
37+
}
38+
}
39+
}
40+
}
41+
```
42+
43+
1. Disables automatic chunking on `my_semantic_field`.
44+
45+
::::
46+
47+
::::{step} Index documents
48+
49+
Index documents with pre-chunked text as an array:
50+
51+
```console
52+
PUT test-index/_doc/1
53+
{
54+
"my_semantic_field": ["my first chunk", "my second chunk", ...] <1>
55+
...
56+
}
57+
```
58+
59+
1. The text is pre-chunked and provided as an array of strings. Each element represents a single chunk.
60+
61+
::::
62+
63+
:::::
64+
65+
:::{important}
66+
When providing pre-chunked input:
67+
68+
- Ensure that you set the chunking strategy to `none` to avoid additional processing.
69+
- Size each chunk carefully, staying within the token limit of the {{infer}} service and the underlying model.
70+
- If a chunk exceeds the model's token limit, the behavior depends on the service:
71+
- Some services (such as OpenAI) will return an error.
72+
- Others (such as `elastic` and `elasticsearch`) will automatically truncate the input.
73+
:::
74+
75+
## Use `copy_to` and multi-fields with `semantic_text` [use-copy-to-with-semantic-text]
76+
77+
You can use a single `semantic_text` field to collect values from multiple fields for semantic search. The `semantic_text` field type can serve as the target of [copy_to fields](/reference/elasticsearch/mapping-reference/copy-to.md), be part of a [multi-field](/reference/elasticsearch/mapping-reference/multi-fields.md) structure, or contain [multi-fields](/reference/elasticsearch/mapping-reference/multi-fields.md) internally.
78+
79+
### Use copy_to
80+
81+
Use `copy_to` to copy values from source fields to a `semantic_text` field:
82+
83+
```console
84+
PUT test-index
85+
{
86+
"mappings": {
87+
"properties": {
88+
"source_field": {
89+
"type": "text",
90+
"copy_to": "infer_field"
91+
},
92+
"infer_field": {
93+
"type": "semantic_text",
94+
"inference_id": ".elser-2-elasticsearch"
95+
}
96+
}
97+
}
98+
}
99+
```
100+
% TEST[skip:Requires {{infer}} endpoint]
101+
102+
### Use multi-fields
103+
104+
Declare `semantic_text` as a multi-field:
105+
106+
```console
107+
PUT test-index
108+
{
109+
"mappings": {
110+
"properties": {
111+
"source_field": {
112+
"type": "text",
113+
"fields": {
114+
"infer_field": {
115+
"type": "semantic_text",
116+
"inference_id": ".elser-2-elasticsearch"
117+
}
118+
}
119+
}
120+
}
121+
}
122+
}
123+
```
124+
% TEST[skip:Requires {{infer}} endpoint]
125+
126+
## Updates and partial updates [updates-and-partial-updates]
127+
128+
When updating documents that contain `semantic_text` fields, it's important to understand how {{infer}} is triggered:
129+
130+
Full document updates
131+
: Full document updates re-run {{infer}} on all `semantic_text` fields, even if their values did not change. This ensures that embeddings remain consistent with the current document state but can increase ingestion costs.
132+
133+
Partial updates using the Bulk API
134+
: Partial updates submitted through the [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) reuse existing embeddings when you omit `semantic_text` fields. {{infer}} does not run for omitted fields, which can significantly reduce processing time and cost.
135+
136+
Partial updates using the Update API
137+
: Partial updates submitted through the [Update API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update) re-run {{infer}} on all `semantic_text` fields, even when you omit them from the `doc` object. Embeddings are re-generated regardless of whether field values changed.
138+
139+
To preserve existing embeddings and avoid unnecessary {{infer}} costs:
140+
141+
* Use partial updates with the Bulk API.
142+
* Omit any `semantic_text` fields that did not change from the `doc` object in your request.
143+
144+
### Scripted updates [scripted-updates]
145+
146+
For indices containing `semantic_text` fields, updates that use scripts have the
147+
following behavior:
148+
149+
- ✅ **Supported:** [Update API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update)
150+
- ❌ **Not supported:** [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk-1). Scripted updates will fail even if the script targets non-`semantic_text` fields.

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

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
navigation_title: "Reference"
3+
mapped_pages:
4+
- https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
5+
applies_to:
6+
stack: ga 9.0
7+
serverless: ga
8+
---
9+
10+
# Semantic text field type reference [semantic-text]
11+
12+
This page provides reference content for the `semantic_text` field type, including parameter descriptions, {{infer}} endpoint configuration options, chunking behavior, update operations, querying options, and limitations.
13+
14+
## Parameters for `semantic_text` [semantic-text-params]
15+
16+
The `semantic_text` field type uses default indexing settings based on the [{{infer}} endpoint](#configuring-inference-endpoints) specified, enabling you to get started without providing additional configuration details. You can override these defaults by customizing the parameters described below.
17+
18+
`inference_id`
19+
: (Optional, string) {{infer-cap}} endpoint that will be used to generate
20+
embeddings for the field. If `search_inference_id` is specified, the {{infer}}
21+
endpoint will only be used at index time. Learn more about [configuring this parameter](#configuring-inference-endpoints).
22+
23+
**Updating the `inference_id` parameter**
24+
25+
::::{applies-switch}
26+
27+
:::{applies-item} { "stack": "ga 9.0" }
28+
This parameter cannot be updated.
29+
:::
30+
31+
:::{applies-item} { "stack": "ga 9.3" }
32+
33+
You can update this parameter by using
34+
the [Update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping).
35+
You can update the {{infer}} endpoint if no values have been indexed or if the new endpoint is compatible with the current one.
36+
37+
::::{important}
38+
When updating an `inference_id` it is important to ensure the new {{infer}} endpoint produces embeddings compatible with those already indexed. This typically means using the same underlying model.
39+
::::
40+
41+
:::
42+
43+
::::
44+
45+
`search_inference_id`
46+
: (Optional, string) The {{infer}} endpoint that will be used to generate
47+
embeddings at query time. Use the [Create {{infer}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put) to create the endpoint. If not specified, the {{infer}} endpoint defined by
48+
`inference_id` will be used at both index and query time.
49+
50+
You can update this parameter by using
51+
the [Update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping).
52+
53+
Learn how to [use dedicated endpoints for ingestion and search](./semantic-text-setup-configuration.md#dedicated-endpoints-for-ingestion-and-search).
54+
55+
`index_options` {applies_to}`stack: ga 9.1`
56+
: (Optional, object) Specifies the index options to override default values
57+
for the field. Currently, `dense_vector` and `sparse_vector` index options are supported. For text embeddings, `index_options` may match any allowed.
58+
59+
- [dense_vector index options](/reference/elasticsearch/mapping-reference/dense-vector.md#dense-vector-index-options)
60+
61+
- [sparse_vector index options](/reference/elasticsearch/mapping-reference/sparse-vector.md#sparse-vectors-params) {applies_to}`stack: ga 9.2`
62+
63+
`chunking_settings` {applies_to}`stack: ga 9.1`
64+
: (Optional, object) Settings for chunking text into smaller passages.
65+
If specified, these will override the chunking settings set in the {{infer-cap}}
66+
endpoint associated with `inference_id`.
67+
68+
If chunking settings are updated, they will not be applied to existing documents
69+
until they are reindexed. Defaults to the optimal chunking settings for [Elastic Rerank](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-rerank.md).
70+
71+
To completely disable chunking, use the `none` chunking strategy.
72+
73+
::::{important}
74+
When using the `none` chunking strategy, if the input exceeds the maximum token limit of the underlying model,
75+
some services (such as OpenAI) may return an error. In contrast, the `elastic` and `elasticsearch` services will
76+
automatically truncate the input to fit within the model's limit.
77+
::::
78+
79+
### Customizing semantic_text indexing
80+
81+
The following example shows how to configure `inference_id`, `index_options` and `chunking_settings` for a `semantic_text` field type:
82+
83+
```console
84+
PUT my-index-000004
85+
{
86+
"mappings": {
87+
"properties": {
88+
"inference_field": {
89+
"type": "semantic_text",
90+
"inference_id": "my-text-embedding-endpoint", <1>
91+
"index_options": { <2>
92+
"dense_vector": {
93+
"type": "int4_flat"
94+
}
95+
},
96+
"chunking_settings": { <3>
97+
"type": "none"
98+
}
99+
}
100+
}
101+
}
102+
}
103+
```
104+
% TEST[skip:Requires {{infer}} endpoint]
105+
106+
1. The `inference_id` of the {{infer}} endpoint to use for generating embeddings.
107+
2. Overrides default index options by specifying `int4_flat` quantization for dense vector embeddings.
108+
3. Disables automatic chunking by setting the chunking strategy to `none`.
109+
110+
::::{note}
111+
{applies_to}`stack: ga 9.1` Newly created indices with `semantic_text` fields using dense embeddings will be
112+
[quantized](/reference/elasticsearch/mapping-reference/dense-vector.md#dense-vector-quantization)
113+
to `bbq_hnsw` automatically as long as they have a minimum of 64 dimensions.
114+
::::
115+
116+
## {{infer-cap}} endpoints [configuring-inference-endpoints]
117+
118+
The `semantic_text` field type specifies an {{infer}} endpoint identifier (`inference_id`) that is used to generate embeddings.
119+
120+
The following {{infer}} endpoint configurations are available:
121+
122+
- [Default and preconfigured endpoints](./semantic-text-setup-configuration.md#default-and-preconfigured-endpoints): Use `semantic_text` without creating an {{infer}} endpoint manually.
123+
124+
- [ELSER on EIS](./semantic-text-setup-configuration.md#using-elser-on-eis): Use the ELSER model through the Elastic {{infer-cap}} Service.
125+
126+
- [Custom endpoints](./semantic-text-setup-configuration.md#using-custom-endpoint): Create your own {{infer}} endpoint using the [Create {{infer}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put) to use custom models or third-party services.
127+
128+
If you use a [custom {{infer}} endpoint](./semantic-text-setup-configuration.md#using-custom-endpoint) through your ML node and not through Elastic {{infer-cap}} Service (EIS), the recommended method is to [use dedicated endpoints for ingestion and search](./semantic-text-setup-configuration.md#dedicated-endpoints-for-ingestion-and-search).
129+
130+
{applies_to}`stack: ga 9.1.0` If you use EIS, you don't have to set up dedicated endpoints.
131+
132+
::::{warning}
133+
Removing an {{infer}} endpoint will cause ingestion of documents and semantic
134+
queries to fail on indices that define `semantic_text` fields with that
135+
{{infer}} endpoint as their `inference_id`. Trying
136+
to [delete an {{infer}} endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-delete)
137+
that is used on a `semantic_text` field will result in an error.
138+
::::
139+
140+
## Chunking [chunking-behavior]
141+
142+
{{infer-cap}} endpoints have a limit on the amount of text they can process. To
143+
allow for large amounts of text to be used in semantic search, `semantic_text`
144+
automatically generates smaller passages if needed, called chunks.
145+
146+
Each chunk refers to a passage of the text and the corresponding embedding
147+
generated from it. When querying, the individual passages will be automatically
148+
searched for each document, and the most relevant passage will be used to
149+
compute a score.
150+
151+
Chunks are stored as start and end character offsets rather than as separate
152+
text strings. These offsets point to the exact location of each chunk within the
153+
original input text.
154+
155+
You can [pre-chunk content](./semantic-text-ingestions.md#pre-chunking) by providing text as arrays before indexing.
156+
157+
Refer to the [{{infer-cap}} API documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put#operation-inference-put-body-application-json-chunking_settings) for values for `chunking_settings` and to [Configuring chunking](docs-content://explore-analyze/elastic-inference/inference-api.md#infer-chunking-config) to learn about different chunking strategies.
158+
159+
160+
## Limitations [limitations]
161+
162+
`semantic_text` field types have the following limitations:
163+
164+
* `semantic_text` fields are not currently supported as elements
165+
of [nested fields](/reference/elasticsearch/mapping-reference/nested.md).
166+
* `semantic_text` fields can't currently be set as part
167+
of [dynamic templates](docs-content://manage-data/data-store/mapping/dynamic-templates.md).
168+
* `semantic_text` fields are not supported in indices created prior to 8.11.0.
169+
* `semantic_text` fields do not support [Cross-Cluster Search (CCS)](docs-content://solutions/search/cross-cluster-search.md) when [`ccs_minimize_roundtrips`](docs-content://solutions/search/cross-cluster-search.md#ccs-network-delays) is set to `false`.
170+
* `semantic_text` fields do not support [Cross-Cluster Search (CCS)](docs-content://solutions/search/cross-cluster-search.md) in [ES|QL](/reference/query-languages/esql.md).
171+
* `semantic_text` fields do not support [Cross-Cluster Replication (CCR)](docs-content://deploy-manage/tools/cross-cluster-replication.md).
172+
173+
174+
## Document count discrepancy in `_cat/indices` [document-count-discrepancy]
175+
176+
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.
177+
This occurs because `semantic_text` stores embeddings in [nested documents](/reference/elasticsearch/mapping-reference/nested.md), one per chunk. The `_cat/indices` API counts all documents in the Lucene index, including these hidden nested documents.
178+
179+
To count only top-level documents, excluding the nested documents that store embeddings, use one of the following APIs:
180+
181+
* `GET /<index>/_count`
182+
* `GET _cat/count/<index>`

0 commit comments

Comments
 (0)