Skip to content

Commit 64868ee

Browse files
committed
[Docs] Add docs for new semantic text query functionality (#119520)
* Update docs with new semantic text functionality * PR feedback * PR feedback * PR Feedback
1 parent 0793749 commit 64868ee

File tree

4 files changed

+13
-6
lines changed

4 files changed

+13
-6
lines changed

docs/reference/mapping/types/semantic-text.asciidoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Long passages are <<auto-text-chunking, automatically chunked>> to smaller secti
1313
The `semantic_text` field type specifies an inference endpoint identifier that will be used to generate embeddings.
1414
You can create the inference endpoint by using the <<put-inference-api>>.
1515
This field type and the <<query-dsl-semantic-query,`semantic` query>> type make it simpler to perform semantic search on your data.
16+
The `semantic_text` field type may also be queried with <<query-dsl-match-query, match>>, <<query-dsl-sparse-vector-query, sparse_vector>> or <<query-dsl-knn-query, knn>> queries.
1617

1718
If you don’t specify an inference endpoint, the `inference_id` field defaults to `.elser-2-elasticsearch`, a preconfigured endpoint for the elasticsearch service.
1819

docs/reference/query-dsl/knn-query.asciidoc

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ Finds the _k_ nearest vectors to a query vector, as measured by a similarity
88
metric. _knn_ query finds nearest vectors through approximate search on indexed
99
dense_vectors. The preferred way to do approximate kNN search is through the
1010
<<knn-search,top level knn section>> of a search request. _knn_ query is reserved for
11-
expert cases, where there is a need to combine this query with other queries.
11+
expert cases, where there is a need to combine this query with other queries, or
12+
perform a kNN search against a <<semantic-text, semantic_text>> field.
1213

1314
[[knn-query-ex-request]]
1415
==== Example request
@@ -77,7 +78,8 @@ POST my-image-index/_search
7778
+
7879
--
7980
(Required, string) The name of the vector field to search against. Must be a
80-
<<index-vectors-knn-search, `dense_vector` field with indexing enabled>>.
81+
<<index-vectors-knn-search, `dense_vector` field with indexing enabled>>, or a
82+
<<semantic-text, `semantic_text` field>> with a compatible dense vector inference model.
8183
--
8284

8385
`query_vector`::
@@ -93,6 +95,7 @@ Either this or `query_vector_builder` must be provided.
9395
--
9496
(Optional, object) Query vector builder.
9597
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-query-vector-builder]
98+
If all queried fields are of type <<semantic-text, semantic_text>>, the inference ID associated with the `semantic_text` field may be inferred.
9699
--
97100

98101
`k`::

docs/reference/query-dsl/match-query.asciidoc

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ provided text is analyzed before matching.
1010
The `match` query is the standard query for performing a full-text search,
1111
including options for fuzzy matching.
1212

13+
`Match` will also work against <<semantic-text, semantic_text>> fields,
14+
however when performing `match` queries against `semantic_text` fields options
15+
that specifically target lexical search such as `fuzziness` or `analyzer` will be ignored.
16+
1317

1418
[[match-query-ex-request]]
1519
==== Example request
@@ -296,4 +300,3 @@ The example above creates a boolean query:
296300

297301
that matches documents with the term `ny` or the conjunction `new AND york`.
298302
By default the parameter `auto_generate_synonyms_phrase_query` is set to `true`.
299-

docs/reference/query-dsl/sparse-vector-query.asciidoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ This can be achieved with one of two strategies:
1111
- Using an {nlp} model to convert query text into a list of token-weight pairs
1212
- Sending in precalculated token-weight pairs as query vectors
1313

14-
These token-weight pairs are then used in a query against a <<sparse-vector,sparse vector>>.
14+
These token-weight pairs are then used in a query against a <<sparse-vector,sparse vector>>
15+
or a <<semantic-text, semantic_text>> field with a compatible sparse inference model.
1516
At query time, query vectors are calculated using the same inference model that was used to create the tokens.
1617
When querying, these query vectors are ORed together with their respective weights, which means scoring is effectively a <<vector-functions-dot-product,dot product>> calculation between stored dimensions and query dimensions.
1718

@@ -65,6 +66,7 @@ GET _search
6566
It must be the same inference ID that was used to create the tokens from the input text.
6667
Only one of `inference_id` and `query_vector` is allowed.
6768
If `inference_id` is specified, `query` must also be specified.
69+
If all queried fields are of type <<semantic-text, semantic_text>>, the inference ID associated with the `semantic_text` field will be inferred.
6870

6971
`query`::
7072
(Optional, string) The query text you want to use for search.
@@ -291,5 +293,3 @@ GET my-index/_search
291293
//TEST[skip: Requires inference]
292294

293295
NOTE: When performing <<modules-cross-cluster-search, cross-cluster search>>, inference is performed on the local cluster.
294-
295-

0 commit comments

Comments
 (0)