From f29b92cb07cd9b840508f951dcfa022e5e720b10 Mon Sep 17 00:00:00 2001
From: Carlos Delgado <6339205+carlosdelest@users.noreply.github.com>
Date: Thu, 11 Jul 2024 14:45:35 +0200
Subject: [PATCH] Group vector queries into new section (#110722)

---
 docs/reference/query-dsl.asciidoc             |  6 +--
 .../query-dsl/sparse-vector-query.asciidoc    | 12 +++---
 .../query-dsl/special-queries.asciidoc        | 13 -------
 .../query-dsl/text-expansion-query.asciidoc   | 12 +++---
 .../query-dsl/vector-queries.asciidoc         | 37 +++++++++++++++++++
 5 files changed, 51 insertions(+), 29 deletions(-)
 create mode 100644 docs/reference/query-dsl/vector-queries.asciidoc

diff --git a/docs/reference/query-dsl.asciidoc b/docs/reference/query-dsl.asciidoc
index 4d5504e5fe7a..2f8f07f21f64 100644
--- a/docs/reference/query-dsl.asciidoc
+++ b/docs/reference/query-dsl.asciidoc
@@ -72,14 +72,12 @@ include::query-dsl/match-all-query.asciidoc[]
 
 include::query-dsl/span-queries.asciidoc[]
 
+include::query-dsl/vector-queries.asciidoc[]
+
 include::query-dsl/special-queries.asciidoc[]
 
 include::query-dsl/term-level-queries.asciidoc[]
 
-include::query-dsl/text-expansion-query.asciidoc[]
-
-include::query-dsl/sparse-vector-query.asciidoc[]
-
 include::query-dsl/minimum-should-match.asciidoc[]
 
 include::query-dsl/multi-term-rewrite.asciidoc[]
diff --git a/docs/reference/query-dsl/sparse-vector-query.asciidoc b/docs/reference/query-dsl/sparse-vector-query.asciidoc
index 80616ff174e3..08dd7ab7f447 100644
--- a/docs/reference/query-dsl/sparse-vector-query.asciidoc
+++ b/docs/reference/query-dsl/sparse-vector-query.asciidoc
@@ -1,5 +1,5 @@
 [[query-dsl-sparse-vector-query]]
-== Sparse vector query
+=== Sparse vector query
 
 ++++
 <titleabbrev>Sparse vector</titleabbrev>
@@ -19,7 +19,7 @@ For example, a stored vector `{"feature_0": 0.12, "feature_1": 1.2, "feature_2":
 
 [discrete]
 [[sparse-vector-query-ex-request]]
-=== Example request using an {nlp} model
+==== Example request using an {nlp} model
 
 [source,console]
 ----
@@ -37,7 +37,7 @@ GET _search
 // TEST[skip: Requires inference]
 
 [discrete]
-=== Example request using precomputed vectors
+==== Example request using precomputed vectors
 
 [source,console]
 ----
@@ -55,7 +55,7 @@ GET _search
 
 [discrete]
 [[sparse-vector-field-params]]
-=== Top level parameters for `sparse_vector`
+==== Top level parameters for `sparse_vector`
 
 `field`::
 (Required, string) The name of the field that contains the token-weight pairs to be searched against.
@@ -120,7 +120,7 @@ NOTE: The default values for `tokens_freq_ratio_threshold` and `tokens_weight_th
 
 [discrete]
 [[sparse-vector-query-example]]
-=== Example ELSER query
+==== Example ELSER query
 
 The following is an example of the `sparse_vector` query that references the ELSER model to perform semantic search.
 For a more detailed description of how to perform semantic search by using ELSER and the `sparse_vector` query, refer to <<semantic-search-elser,this tutorial>>.
@@ -241,7 +241,7 @@ GET my-index/_search
 
 [discrete]
 [[sparse-vector-query-with-pruning-config-and-rescore-example]]
-=== Example ELSER query with pruning configuration and rescore
+==== Example ELSER query with pruning configuration and rescore
 
 The following is an extension to the above example that adds a preview:[] pruning configuration to the `sparse_vector` query.
 The pruning configuration identifies non-significant tokens to prune from the query in order to improve query performance.
diff --git a/docs/reference/query-dsl/special-queries.asciidoc b/docs/reference/query-dsl/special-queries.asciidoc
index 90cd9a696a6d..a6d35d4f9b70 100644
--- a/docs/reference/query-dsl/special-queries.asciidoc
+++ b/docs/reference/query-dsl/special-queries.asciidoc
@@ -17,10 +17,6 @@ or collection of documents.
 This query finds queries that are stored as documents that match with
 the specified document.
 
-<<query-dsl-knn-query,`knn` query>>::
-A query that finds the _k_ nearest vectors to a query
-vector, as measured by a similarity metric.
-
 <<query-dsl-rank-feature-query,`rank_feature` query>>::
 A query that computes scores based on the values of numeric features and is
 able to efficiently skip non-competitive hits.
@@ -32,9 +28,6 @@ This query allows a script to act as a filter. Also see the
 <<query-dsl-script-score-query,`script_score` query>>::
 A query that allows to modify the score of a sub-query with a script.
 
-<<query-dsl-semantic-query,`semantic` query>>::
-A query that allows you to perform semantic search.
-
 <<query-dsl-wrapper-query,`wrapper` query>>::
 A query that accepts other queries as json or yaml string.
 
@@ -50,20 +43,14 @@ include::mlt-query.asciidoc[]
 
 include::percolate-query.asciidoc[]
 
-include::knn-query.asciidoc[]
-
 include::rank-feature-query.asciidoc[]
 
 include::script-query.asciidoc[]
 
 include::script-score-query.asciidoc[]
 
-include::semantic-query.asciidoc[]
-
 include::wrapper-query.asciidoc[]
 
 include::pinned-query.asciidoc[]
 
 include::rule-query.asciidoc[]
-
-include::weighted-tokens-query.asciidoc[]
diff --git a/docs/reference/query-dsl/text-expansion-query.asciidoc b/docs/reference/query-dsl/text-expansion-query.asciidoc
index 1c51429b5aa2..8faecad1dbdb 100644
--- a/docs/reference/query-dsl/text-expansion-query.asciidoc
+++ b/docs/reference/query-dsl/text-expansion-query.asciidoc
@@ -1,5 +1,5 @@
 [[query-dsl-text-expansion-query]]
-== Text expansion query
+=== Text expansion query
 
 ++++
 <titleabbrev>Text expansion</titleabbrev>
@@ -12,7 +12,7 @@ The text expansion query uses a {nlp} model to convert the query text into a lis
 
 [discrete]
 [[text-expansion-query-ex-request]]
-=== Example request
+==== Example request
 
 [source,console]
 ----
@@ -32,14 +32,14 @@ GET _search
 
 [discrete]
 [[text-expansion-query-params]]
-=== Top level parameters for `text_expansion`
+==== Top level parameters for `text_expansion`
 
 `<sparse_vector_field>`:::
 (Required, object) The name of the field that contains the token-weight pairs the NLP model created based on the input text.
 
 [discrete]
 [[text-expansion-rank-feature-field-params]]
-=== Top level parameters for `<sparse_vector_field>`
+==== Top level parameters for `<sparse_vector_field>`
 
 `model_id`::::
 (Required, string) The ID of the model to use to convert the query text into token-weight pairs.
@@ -84,7 +84,7 @@ NOTE: The default values for `tokens_freq_ratio_threshold` and `tokens_weight_th
 
 [discrete]
 [[text-expansion-query-example]]
-=== Example ELSER query
+==== Example ELSER query
 
 The following is an example of the `text_expansion` query that references the ELSER model to perform semantic search.
 For a more detailed description of how to perform semantic search by using ELSER and the `text_expansion` query, refer to <<semantic-search-elser,this tutorial>>.
@@ -208,7 +208,7 @@ GET my-index/_search
 
 [discrete]
 [[text-expansion-query-with-pruning-config-and-rescore-example]]
-=== Example ELSER query with pruning configuration and rescore
+==== Example ELSER query with pruning configuration and rescore
 
 The following is an extension to the above example that adds a preview:[] pruning configuration to the `text_expansion` query.
 The pruning configuration identifies non-significant tokens to prune from the query in order to improve query performance.
diff --git a/docs/reference/query-dsl/vector-queries.asciidoc b/docs/reference/query-dsl/vector-queries.asciidoc
new file mode 100644
index 000000000000..fe9f380eeb62
--- /dev/null
+++ b/docs/reference/query-dsl/vector-queries.asciidoc
@@ -0,0 +1,37 @@
+[[vector-queries]]
+== Vector queries
+
+Vector queries are specialized queries that work on vector fields to efficiently perform <<semantic-search,semantic search>>.
+
+<<query-dsl-knn-query,`knn` query>>::
+A query that finds the _k_ nearest vectors to a query vector for <<dense-vector,`dense_vector`>> fields, as measured by a similarity metric.
+
+<<query-dsl-sparse-vector-query,`sparse_vector` query>>::
+A query used to search <<sparse-vector,`sparse_vector`>> field types.
+
+<<query-dsl-semantic-query,`semantic` query>>::
+A query that allows you to perform semantic search on <<semantic-text,`semantic_text`>> fields.
+
+[discrete]
+=== Deprecated vector queries
+
+The following queries have been deprecated and will be removed in the near future.
+Use the <<query-dsl-sparse-vector-query,`sparse_vector` query>> query instead.
+
+<<query-dsl-text-expansion-query,`text_expansion` query>>::
+A query that allows you to perform sparse vector search on <<sparse-vector,`sparse_vector`>> or <<rank-features,`rank_features`>> fields.
+
+<<query-dsl-weighted-tokens-query,`weighted_tokens` query>>::
+Allows to perform text expansion queries optimizing for performance.
+
+include::knn-query.asciidoc[]
+
+include::sparse-vector-query.asciidoc[]
+
+include::semantic-query.asciidoc[]
+
+include::text-expansion-query.asciidoc[]
+
+include::weighted-tokens-query.asciidoc[]
+
+