diff --git a/docs/reference/elasticsearch/mapping-reference/semantic-text.md b/docs/reference/elasticsearch/mapping-reference/semantic-text.md
index 8588b946b0f62..4965d5fc16286 100644
--- a/docs/reference/elasticsearch/mapping-reference/semantic-text.md
+++ b/docs/reference/elasticsearch/mapping-reference/semantic-text.md
@@ -611,6 +611,31 @@ PUT test-index
 }
 ```
 
+## Querying `semantic_text` fields [querying-semantic-text-fields]
+
+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.md#esql-match) syntax.
+<!--
+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 such as [ELSER](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-elser.md).
+<!-- 
+Refer to examples of sparse vector queries on `semantic_text` fields.
+-->
+
+- [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.
+<!-- 
+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
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.