From 8ade227a68eb83a198c62ccb1d041a194a7cb69f Mon Sep 17 00:00:00 2001
From: carlosdelest <carlos.delgado@elastic.co>
Date: Wed, 11 Dec 2024 10:45:50 +0100
Subject: [PATCH] Refactor common params

---
 docs/reference/query-dsl/knn-query.asciidoc   |  8 ++------
 docs/reference/rest-api/common-parms.asciidoc | 18 +++++++++++-------
 docs/reference/search/retriever.asciidoc      |  7 +------
 3 files changed, 14 insertions(+), 19 deletions(-)

diff --git a/docs/reference/query-dsl/knn-query.asciidoc b/docs/reference/query-dsl/knn-query.asciidoc
index cae6b0e80c4ba..604c29c705a39 100644
--- a/docs/reference/query-dsl/knn-query.asciidoc
+++ b/docs/reference/query-dsl/knn-query.asciidoc
@@ -134,12 +134,8 @@ documents are then scored according to <<dense-vector-similarity, `similarity`>>
 and the provided `boost` is applied.
 --
 
-`rescore`::
-+
---
-(Optional, object) Rescoring to apply to quantized vectors.
-include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-rescore]
---
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-rescore-vector]
+
 
 `boost`::
 +
diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
index f8d472d350071..ffe1c9b275072 100644
--- a/docs/reference/rest-api/common-parms.asciidoc
+++ b/docs/reference/rest-api/common-parms.asciidoc
@@ -1347,18 +1347,22 @@ Applies the specified <<query-dsl-bool-query, boolean query filter>> to all of t
 according to each retriever's specifications.
 end::rrf-filter[]
 
-tag::knn-rescore[]
+tag::knn-rescore-vector[]
+
+`rescore_vector`::
++
+--
+(Optional, object) Functionality in preview:[]. Apply oversampling and rescoring to quantized vectors.
 
 NOTE: Rescoring only makes sense for quantized vectors; when <<dense-vector-quantization,quantization>> is not used, the original vectors are used for scoring.
 Rescore option will be ignored for non-quantized `dense_vector` fields.
 
-`oversample`::
+`num_candidates_factor`::
 (Required, float)
 +
-Applies the specified oversample factor to the approximate kNN search.
-The approximate kNN search will retrieve the top `k * oversample` candidates per shard,
-and then use the original vectors for rescoring.
-The top `k` rescored candidates will be returned as results.
+Applies the specified oversample factor to the number of candidates on the approximate kNN search.
+The approximate kNN search will retrieve `num_candidates * num_candidates_factor` candidates per shard, and then use the original vectors for rescoring them.
 
 See <<dense-vector-knn-search-reranking,oversampling and rescoring quantized vectors>> for details.
-end::knn-rescore[]
+--
+end::knn-rescore-vector[]
diff --git a/docs/reference/search/retriever.asciidoc b/docs/reference/search/retriever.asciidoc
index cb4b8a4f6c493..9ddedf274d31f 100644
--- a/docs/reference/search/retriever.asciidoc
+++ b/docs/reference/search/retriever.asciidoc
@@ -224,12 +224,7 @@ include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-filter]
 +
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-similarity]
 
-`rescore`::
-+
---
-(Optional, object) Rescoring to apply to quantized vectors.
-include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-rescore]
---
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=knn-rescore-vector]
 
 ===== Restrictions