diff --git a/docs/reference/query-languages/query-dsl/query-dsl-semantic-query.md b/docs/reference/query-languages/query-dsl/query-dsl-semantic-query.md index 67c262c1ad58b..fdc6df5c81cdc 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-semantic-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-semantic-query.md @@ -13,8 +13,18 @@ applies_to: We don't recommend this legacy query type for _new_ projects. Use the match query (with [QueryDSL](/reference/query-languages/query-dsl/query-dsl-match-query.md) or [ESQL](/reference/query-languages/esql/functions-operators/search-functions.md#esql-match)) instead. The semantic query remains available to support existing implementations. :::: -The `semantic` query type enables you to perform [semantic search](docs-content://solutions/search/semantic-search.md) on data stored in a [`semantic_text`](/reference/elasticsearch/mapping-reference/semantic-text.md) field. +The `semantic` query type enables you to perform [semantic search](docs-content://solutions/search/semantic-search.md) on data stored in a [`semantic_text`](/reference/elasticsearch/mapping-reference/semantic-text.md) field. This query accepts natural-language text and uses the field’s configured inference endpoint to generate a query embedding and score documents. +For an overview of all query options available for `semantic_text` fields, see [Querying `semantic_text` fields](/reference/elasticsearch/mapping-reference/semantic-text.md#querying-semantic-text-fields). + +## Inference endpoint selection + +The target field of `semantic` query must be mapped as `semantic_text` and associated with an inference endpoint. At query time, the inference endpoint is chosen as follows: +- If `search_inference_id` is defined, the semantic query uses that endpoint to embed the query. +- If no `search_inference_id` is defined, `inference_id` is used for both indexing and search. +- If no endpoint is specified at mapping, `inference_id` defaults to `.elser-2-elasticsearch`. + +The underlying vector mode (dense or sparse) follows the field’s endpoint automatically. No extra query parameters are required. ## Example request [semantic-query-example] diff --git a/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md b/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md index cdc2613a3aa24..860a09edee306 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md @@ -203,6 +203,54 @@ GET my-index/_search } ``` +## Example query on a `semantic_text` field + +You can also run a `sparse_vector` query directly on a [`semantic_text`](/reference/elasticsearch/mapping-reference/semantic-text.md) field. In this case Elasticsearch automatically uses the inference endpoint configured in the field mapping to expand the query into sparse tokens. + +First, create an index with a `semantic_text` field: + +```console +PUT /my-semantic-sparse-index +{ + "mappings": { + "properties": { + "title": { "type": "text" }, + "content_semantic": { + "type": "semantic_text", + "inference_id": ".elser-2-elasticsearch" + } + } + } +} +``` + +Index some example documents: + +```console +POST /my-semantic-sparse-index/_bulk +{ "index": { "_index": "my-semantic-sparse-index", "_id": "1" } } +{ "title": "Best surfing spots", "content_semantic": "Hawaii has world-class surfing with warm water and consistent swells." } +{ "index": { "_index": "my-semantic-sparse-index", "_id": "2" } } +{ "title": "City breaks", "content_semantic": "Paris offers museums, cafés, and beautiful architecture." } +{ "index": { "_index": "my-semantic-sparse-index", "_id": "3" } } +{ "title": "Learning to surf", "content_semantic": "Beginners often start on longboards at gentle beach breaks." } +``` + +Then query with `sparse_vector` against the `semantic_text` field: + +```console +GET my-semantic-sparse-index/_search +{ + "size": 3, + "query": { + "sparse_vector": { + "field": "content_semantic", + "query": "best places to surf as a beginner" + } + } +} +``` + ## Example ELSER query with pruning configuration and rescore [sparse-vector-query-with-pruning-config-and-rescore-example]