Skip to content

Commit 5d22ad6

Browse files
kderussoleemthompo
andauthored
Add clarification to semantic_text documentation on default quantization and lexical search support (#128927)
* Add clarifications to semantic text documentation * Regnerate match ESQL docs * Fix whitespace * PR feedback * Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --------- Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
1 parent 110bbe8 commit 5d22ad6

File tree

6 files changed

+21
-8
lines changed

6 files changed

+21
-8
lines changed

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

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ service.
2828

2929
Using `semantic_text`, you won’t need to specify how to generate embeddings for
3030
your data, or how to index it. The {{infer}} endpoint automatically determines
31-
the embedding generation, indexing, and query to use.
31+
the embedding generation, indexing, and query to use.
32+
Newly created indices with `semantic_text` fields using dense embeddings will be
33+
[quantized](/reference/elasticsearch/mapping-reference/dense-vector.md#dense-vector-quantization)
34+
to `bbq_hnsw` automatically.
3235

3336
If you use the preconfigured `.elser-2-elasticsearch` endpoint, you can set up
3437
`semantic_text` with the following API request:
@@ -246,10 +249,15 @@ is not supported for querying the field data.
246249

247250
## Updates to `semantic_text` fields [update-script]
248251

249-
For indices containing `semantic_text` fields, updates that use scripts have the following behavior:
252+
For indices containing `semantic_text` fields, updates that use scripts have the
253+
following behavior:
250254

251-
* Are supported through the [Update API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update).
252-
* Are not supported through the [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk-1) and will fail. Even if the script targets non-`semantic_text` fields, the update will fail when the index contains a `semantic_text` field.
255+
* Are supported through
256+
the [Update API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update).
257+
* Are not supported through
258+
the [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk-1)
259+
and will fail. Even if the script targets non-`semantic_text` fields, the
260+
update will fail when the index contains a `semantic_text` field.
253261

254262
## `copy_to` and multi-fields support [copy-to-support]
255263

@@ -311,4 +319,5 @@ PUT test-index
311319
of [nested fields](/reference/elasticsearch/mapping-reference/nested.md).
312320
* `semantic_text` fields can’t currently be set as part
313321
of [Dynamic templates](docs-content://manage-data/data-store/mapping/dynamic-templates.md).
314-
* `semantic_text` fields are not supported with Cross-Cluster Search (CCS) or Cross-Cluster Replication (CCR).
322+
* `semantic_text` fields are not supported with Cross-Cluster Search (CCS) or
323+
Cross-Cluster Replication (CCR).

docs/reference/query-languages/esql/_snippets/functions/description/match.md

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/reference/query-languages/esql/kibana/definition/functions/match.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/reference/query-languages/esql/kibana/docs/functions/match.md

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/reference/query-languages/query-dsl/query-dsl-match-query.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ Returns documents that match a provided text, number, date or boolean value. The
1111

1212
The `match` query is the standard query for performing a full-text search, including options for fuzzy matching.
1313

14-
`Match` will also work against [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md) fields, however when performing `match` queries against `semantic_text` fields options that specifically target lexical search such as `fuzziness` or `analyzer` will be ignored.
14+
`Match` will also work against [semantic_text](/reference/elasticsearch/mapping-reference/semantic-text.md) fields.
15+
As `semantic_text` does not support lexical text search, `match` queries against `semantic_text` fields will automatically perform the correct semantic search.
16+
Because of this, options that specifically target lexical search such as `fuzziness` or `analyzer` will be ignored.
1517

1618
## Example request [match-query-ex-request]
1719

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/fulltext/Match.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,7 @@ public class Match extends FullTextFunction implements OptionalArgument, PostAna
142142
143143
Match can be used on fields from the text family like <<text, text>> and <<semantic-text, semantic_text>>,
144144
as well as other field types like keyword, boolean, dates, and numeric types.
145+
When Match is used on a <<semantic-text, semantic_text>> field, it will perform a semantic query on the field.
145146
146147
Match can use <<esql-function-named-params,function named parameters>> to specify additional options for the match query.
147148
All <<match-field-params,match query parameters>> are supported.

0 commit comments

Comments
 (0)