From f126b9b6db91e2ebd55bea17f75328f75e4b5094 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Tue, 7 Oct 2025 12:43:40 +0200 Subject: [PATCH 01/10] Adds Querying semantic_text fields section --- .../mapping-reference/semantic-text.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index 8588b946b0f62..38b060bc09db6 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -611,6 +611,21 @@ PUT test-index } ``` +## Querying `semantic_text` fields [querying-semantic-text-fields] + +Querying `semantic_text` fields enables semantic search by matching on meaning rather than just keywords. It’s useful for natural language search, intent-aware retrieval, and cases where keyword matching alone isn’t sufficient. + +You can query `semantic_text` fields using the following query types: + +- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. Refer to examples of match queries on `semantic_text` fields. + +- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) - Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. Refer to examples of kNN queries on `semantic_text` fields. + +- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. Refer to examples of sparse vector queries on `semantic_text` fields. + +- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. Refer to examples of semantic queries on `semantic_text` fields. + + ## Troubleshooting semantic_text fields [troubleshooting-semantic-text-fields] If you want to verify that your embeddings look correct, you can view the From 6cfaf35213c916710ebd096b0cd16ea0222be6d6 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Tue, 7 Oct 2025 14:24:46 +0200 Subject: [PATCH 02/10] Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index 38b060bc09db6..c5f5001173c77 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -613,7 +613,6 @@ PUT test-index ## Querying `semantic_text` fields [querying-semantic-text-fields] -Querying `semantic_text` fields enables semantic search by matching on meaning rather than just keywords. It’s useful for natural language search, intent-aware retrieval, and cases where keyword matching alone isn’t sufficient. You can query `semantic_text` fields using the following query types: From 50a5e24c5829e9fe9211adfc1c453d50e27dfe31 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Tue, 7 Oct 2025 14:55:47 +0200 Subject: [PATCH 03/10] Comment out links temporarily --- .../mapping-reference/semantic-text.md | 27 +++++++++++++------ 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index c5f5001173c77..a56e5ab7aeebc 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -613,16 +613,27 @@ PUT test-index ## Querying `semantic_text` fields [querying-semantic-text-fields] - You can query `semantic_text` fields using the following query types: -- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. Refer to examples of match queries on `semantic_text` fields. - -- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) - Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. Refer to examples of kNN queries on `semantic_text` fields. - -- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. Refer to examples of sparse vector queries on `semantic_text` fields. - -- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. Refer to examples of semantic queries on `semantic_text` fields. +- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. + + +- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) - Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. + + +- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. + + +- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. + ## Troubleshooting semantic_text fields [troubleshooting-semantic-text-fields] From 67d9f5c63532620fc5de8b9bd65fa0e47c435581 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Tue, 7 Oct 2025 15:31:45 +0200 Subject: [PATCH 04/10] Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index a56e5ab7aeebc..a54fb58e69918 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -615,7 +615,7 @@ PUT test-index You can query `semantic_text` fields using the following query types: -- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md) - The recommended method for querying `semantic_text` fields. +- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md): The recommended method for querying `semantic_text` fields. From 11089a76cfd3ac4a09ea2589b24284c141c1ac6b Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Tue, 7 Oct 2025 15:32:03 +0200 Subject: [PATCH 05/10] Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index a54fb58e69918..3328ad3942c88 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -620,7 +620,7 @@ You can query `semantic_text` fields using the following query types: Refer to examples of match queries on `semantic_text` fields. --> -- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) - Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. +- [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md): Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. From 38a79dea79aaa224288e00bc5a75683e9644ac3e Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Tue, 7 Oct 2025 15:32:23 +0200 Subject: [PATCH 06/10] Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index 3328ad3942c88..4e77dc83bc639 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -625,7 +625,7 @@ Refer to examples of match queries on `semantic_text` fields. Refer to examples of kNN queries on `semantic_text` fields. --> -- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) - Executes searches using sparse vectors generated by a sparse retrieval model. +- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md): Executes searches using sparse vectors generated by a sparse retrieval model such as [ELSER](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-elser.md) From a8435b60e4e8ce18464b62204f24ae2afc96c2f3 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Tue, 7 Oct 2025 15:32:36 +0200 Subject: [PATCH 07/10] Update docs/reference/elasticsearch/mapping-reference/semantic-text.md Co-authored-by: Liam Thompson --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index 4e77dc83bc639..afaf2c846320e 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -630,7 +630,7 @@ Refer to examples of kNN queries on `semantic_text` fields. Refer to examples of sparse vector queries on `semantic_text` fields. --> -- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md) - A legacy option that was introduced earlier and is no longer recommended, but it remains supported for existing implementations. +- [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. From 1cdabcb08d97b8738bad58a58fe51c58acaaf3e4 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Wed, 8 Oct 2025 11:26:12 +0200 Subject: [PATCH 08/10] Adds ESQL link to match query --- .../elasticsearch/mapping-reference/semantic-text.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index afaf2c846320e..f82e00cdfa9f3 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -615,17 +615,17 @@ PUT test-index You can query `semantic_text` fields using the following query types: -- [Match query](/reference/query-languages/query-dsl/query-dsl-match-query.md): The recommended method for querying `semantic_text` fields. +- Match query: The recommended method for querying `semantic_text` fields. You can use [Query DSL](/reference/query-languages/query-dsl/query-dsl-match-query.md) or [ES|QL](/reference/query-languages/esql/functions-operators/search-functions#esql-match) syntax. - [kNN query](/reference/query-languages/query-dsl/query-dsl-knn-query.md): Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. -- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md): Executes searches using sparse vectors generated by a sparse retrieval model such as [ELSER](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-elser.md) +- [Sparse vector query](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md): Executes searches using sparse vectors generated by a sparse retrieval model such as [ELSER](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-elser.md). From 30b9341245d56cc1c94d50ab01125ef8b2274f52 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Wed, 8 Oct 2025 11:31:55 +0200 Subject: [PATCH 09/10] Fixes link --- docs/reference/elasticsearch/mapping-reference/semantic-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md index f82e00cdfa9f3..4965d5fc16286 100644 --- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md +++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md @@ -615,7 +615,7 @@ PUT test-index You can query `semantic_text` fields using the following query types: -- Match query: The recommended method for querying `semantic_text` fields. You can use [Query DSL](/reference/query-languages/query-dsl/query-dsl-match-query.md) or [ES|QL](/reference/query-languages/esql/functions-operators/search-functions#esql-match) syntax. +- Match query: The recommended method for querying `semantic_text` fields. You can use [Query DSL](/reference/query-languages/query-dsl/query-dsl-match-query.md) or [ES|QL](/reference/query-languages/esql/functions-operators/search-functions.md#esql-match) syntax. From 964aec6f1ad560fb77efb9dfcc2f897c2390bfce Mon Sep 17 00:00:00 2001 From: kosabogi Date: Wed, 8 Oct 2025 13:34:19 +0200 Subject: [PATCH 10/10] Adds note to the Semantic query page --- .../query-languages/query-dsl/query-dsl-semantic-query.md | 4 ++++ 1 file changed, 4 insertions(+) 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 ebad528a2ad92..67c262c1ad58b 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 @@ -9,6 +9,10 @@ applies_to: # Semantic query [query-dsl-semantic-query] +::::{note} +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.