From 70a6cddacba919f0eeb94a895992c5c9df633019 Mon Sep 17 00:00:00 2001 From: Aireza Heidarikhazaei Date: Wed, 18 Feb 2026 22:05:55 -0800 Subject: [PATCH 01/11] Documentation for query_vector parameter Update documentation for query_vector parameter in diversify and knn retrievers to include base64-encoded vector string support and clarify hex-encoded byte vector usage. Relates to #138190 --- .../retrievers/diversify-retriever.md | 4 +-- .../rest-apis/retrievers/knn-retriever.md | 4 +-- .../query-dsl/query-dsl-knn-query.md | 36 ++++++++++++++++++- 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md index 969dc02612c0b..a8a3d65dcfb44 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md @@ -46,10 +46,10 @@ The ordering of results returned from the inner retriever is preserved. ::: `query_vector` -: (Optional, array of `float` or `byte`) +: (Optional, array of `float` or `byte`, or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats or a hex-encoded byte vector. + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. If you provide a `query_vector`, you cannot also provide a `query_vector_builder`. `query_vector_builder` diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md index b64ea8216e7a5..86e9b183905f8 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md @@ -18,9 +18,9 @@ A kNN retriever returns top documents from a [k-nearest neighbor search (kNN)](d `query_vector` -: (Required if `query_vector_builder` is not defined, array of `float`) +: (Required if `query_vector_builder` is not defined, array of `float` or string) - Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats or a hex-encoded byte vector. + Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. `query_vector_builder` diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index 8ef32305e32b6..9850d1bfe46b3 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -66,6 +66,40 @@ PUT my-image-index ``` % TEST[continued] +3. You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. + + ```console + POST my-image-index/_search + { + "size" : 3, + "query" : { + "knn": { + "field": "image-vector", + "query_vector": "wKAAAEEQAADBQAAA", + "k": 10 + } + } + } + ``` + % TEST[continued] + +4. You can also provide a hex-encoded query vector string. Hex query vectors are byte-oriented (one byte per dimension, represented as two hex characters). For example, `[-5, 9, -12]` as signed bytes is `fb09f4`. + + ```console + POST my-image-index/_search + { + "size" : 3, + "query" : { + "knn": { + "field": "image-vector", + "query_vector": "fb09f4", + "k": 10 + } + } + } + ``` + % TEST[continued] + ## Top-level parameters for `knn` [knn-query-top-level-parameters] @@ -74,7 +108,7 @@ PUT my-image-index `query_vector` -: (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats or a hex-encoded byte vector. Either this or `query_vector_builder` must be provided. +: (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. Either this or `query_vector_builder` must be provided. `query_vector_builder` From d5b57a846cabd2389cce31609d701abe49bd5595 Mon Sep 17 00:00:00 2001 From: Aireza Heidarikhazaei Date: Wed, 18 Feb 2026 23:16:11 -0800 Subject: [PATCH 02/11] Added tag --- .../retrievers/diversify-retriever.md | 3 ++- .../rest-apis/retrievers/knn-retriever.md | 4 +++- .../query-dsl/query-dsl-knn-query.md | 18 +++++++++++++----- 3 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md index a8a3d65dcfb44..79998becec2b4 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md @@ -49,7 +49,8 @@ The ordering of results returned from the inner retriever is preserved. : (Optional, array of `float` or `byte`, or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. + Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` If you provide a `query_vector`, you cannot also provide a `query_vector_builder`. `query_vector_builder` diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md index 86e9b183905f8..a245674be1817 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md @@ -20,7 +20,9 @@ A kNN retriever returns top documents from a [k-nearest neighbor search (kNN)](d `query_vector` : (Required if `query_vector_builder` is not defined, array of `float` or string) - Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. + Query vector. Must have the same number of dimensions as the vector field you are searching against. + Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. `query_vector_builder` diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index 9850d1bfe46b3..c1796c82a4cef 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -66,7 +66,7 @@ PUT my-image-index ``` % TEST[continued] -3. You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. +3. You can also provide a hex-encoded query vector string. Hex query vectors are byte-oriented (one byte per dimension, represented as two hex characters). For example, `[-5, 9, -12]` as signed bytes is `fb09f4`. ```console POST my-image-index/_search @@ -75,7 +75,7 @@ PUT my-image-index "query" : { "knn": { "field": "image-vector", - "query_vector": "wKAAAEEQAADBQAAA", + "query_vector": "fb09f4", "k": 10 } } @@ -83,7 +83,12 @@ PUT my-image-index ``` % TEST[continued] -4. You can also provide a hex-encoded query vector string. Hex query vectors are byte-oriented (one byte per dimension, represented as two hex characters). For example, `[-5, 9, -12]` as signed bytes is `fb09f4`. +```{applies_to} +stack: ga 9.4 +serverless: ga +``` + +4. You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. ```console POST my-image-index/_search @@ -92,7 +97,7 @@ PUT my-image-index "query" : { "knn": { "field": "image-vector", - "query_vector": "fb09f4", + "query_vector": "wKAAAEEQAADBQAAA", "k": 10 } } @@ -108,7 +113,10 @@ PUT my-image-index `query_vector` -: (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. Either this or `query_vector_builder` must be provided. +: (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. + Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). + It can also be a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` + Either this or `query_vector_builder` must be provided. `query_vector_builder` From 8495aa5605d7d359ada68ecbe218ed13c24c628f Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Thu, 19 Feb 2026 12:49:20 -0800 Subject: [PATCH 03/11] Update docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md Co-authored-by: Benjamin Trent --- .../elasticsearch/rest-apis/retrievers/diversify-retriever.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md index 79998becec2b4..11f25500eb4b6 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md @@ -50,7 +50,7 @@ The ordering of results returned from the inner retriever is preserved. Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions){applies_to}`stack: ga 9.0-9.3`, or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` If you provide a `query_vector`, you cannot also provide a `query_vector_builder`. `query_vector_builder` From e839d7c2577f3b9fb4247e7b50da4d72913091e4 Mon Sep 17 00:00:00 2001 From: Aireza Heidarikhazaei Date: Thu, 19 Feb 2026 13:38:15 -0800 Subject: [PATCH 04/11] Update documentation for query_vector parameter Adding big-endianess --- .../elasticsearch/rest-apis/retrievers/diversify-retriever.md | 3 +-- .../elasticsearch/rest-apis/retrievers/knn-retriever.md | 2 +- .../reference/query-languages/query-dsl/query-dsl-knn-query.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md index 11f25500eb4b6..457a7713a1b06 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md @@ -49,8 +49,7 @@ The ordering of results returned from the inner retriever is preserved. : (Optional, array of `float` or `byte`, or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions){applies_to}`stack: ga 9.0-9.3`, or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions){applies_to}`stack: ga 9.0-9.3`, or a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` If you provide a `query_vector`, you cannot also provide a `query_vector_builder`. `query_vector_builder` diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md index a245674be1817..6620cda25b428 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md @@ -22,7 +22,7 @@ A kNN retriever returns top documents from a [k-nearest neighbor search (kNN)](d Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` or a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. + Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` or a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. `query_vector_builder` diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index c1796c82a4cef..e3bd524c4a6fe 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -115,7 +115,7 @@ serverless: ga `query_vector` : (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). - It can also be a base64-encoded vector string. Base64 supports `float`, `bfloat16`, `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` + It can also be a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` Either this or `query_vector_builder` must be provided. From e1f601c3636aadea0fea0697ef55b3d84fbde7c2 Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Mon, 23 Feb 2026 09:26:58 -0800 Subject: [PATCH 05/11] Update docs/reference/query-languages/query-dsl/query-dsl-knn-query.md Co-authored-by: Liam Thompson --- .../reference/query-languages/query-dsl/query-dsl-knn-query.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index e3bd524c4a6fe..d4cb7bc024d67 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -83,9 +83,6 @@ PUT my-image-index ``` % TEST[continued] -```{applies_to} -stack: ga 9.4 -serverless: ga ``` 4. You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. From 033f9bed35715da12d6cdf42139bde4815ea8d3b Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Mon, 23 Feb 2026 09:27:09 -0800 Subject: [PATCH 06/11] Update docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md Co-authored-by: Liam Thompson --- .../rest-apis/retrievers/diversify-retriever.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md index 457a7713a1b06..76d54528e0d2b 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/diversify-retriever.md @@ -49,7 +49,10 @@ The ordering of results returned from the inner retriever is preserved. : (Optional, array of `float` or `byte`, or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions){applies_to}`stack: ga 9.0-9.3`, or a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` + Must be one of: + - An array of floats + - A hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions){applies_to}`stack: ga 9.0-9.3` + - A base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` If you provide a `query_vector`, you cannot also provide a `query_vector_builder`. `query_vector_builder` From 8f76709e958c698ac030a3b81393db72e75e1009 Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Mon, 23 Feb 2026 09:27:20 -0800 Subject: [PATCH 07/11] Update docs/reference/query-languages/query-dsl/query-dsl-knn-query.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/query-dsl/query-dsl-knn-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index d4cb7bc024d67..296196ce99740 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -66,7 +66,7 @@ PUT my-image-index ``` % TEST[continued] -3. You can also provide a hex-encoded query vector string. Hex query vectors are byte-oriented (one byte per dimension, represented as two hex characters). For example, `[-5, 9, -12]` as signed bytes is `fb09f4`. +3. {applies_to}`stack: ga 9.0-9.3` You can also provide a hex-encoded query vector string. Hex query vectors are byte-oriented (one byte per dimension, represented as two hex characters). For example, `[-5, 9, -12]` as signed bytes is `fb09f4`. ```console POST my-image-index/_search From b523683ba0b3365ac9a0a803ca98baffa8e60e3b Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Mon, 23 Feb 2026 09:27:28 -0800 Subject: [PATCH 08/11] Update docs/reference/query-languages/query-dsl/query-dsl-knn-query.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/query-dsl/query-dsl-knn-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index 296196ce99740..b92d69dcb0015 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -85,7 +85,7 @@ PUT my-image-index ``` -4. You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. +4. {applies_to}`stack: ga 9.4` You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. ```console POST my-image-index/_search From edf33b2ab5fd01cbba2a91a1609e6f4c8639ff4a Mon Sep 17 00:00:00 2001 From: Alireza Heidarikhazaei Date: Mon, 23 Feb 2026 09:27:42 -0800 Subject: [PATCH 09/11] Update docs/reference/query-languages/query-dsl/query-dsl-knn-query.md Co-authored-by: Liam Thompson --- docs/reference/query-languages/query-dsl/query-dsl-knn-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index b92d69dcb0015..c437171dbe278 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -111,7 +111,7 @@ PUT my-image-index `query_vector` : (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). + Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` It can also be a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` Either this or `query_vector_builder` must be provided. From 3e07efa3257ec9ebac68b524b32d3d25003c5077 Mon Sep 17 00:00:00 2001 From: Aireza Heidarikhazaei Date: Tue, 24 Feb 2026 09:34:58 -0800 Subject: [PATCH 10/11] Removes redundant code block from documentation Eliminates an unnecessary code block for improved clarity and readability in the documentation. No content functionality is affected. --- docs/reference/query-languages/query-dsl/query-dsl-knn-query.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index c437171dbe278..cd290de2d749d 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -83,8 +83,6 @@ PUT my-image-index ``` % TEST[continued] -``` - 4. {applies_to}`stack: ga 9.4` You can also provide a base64-encoded query vector string. For example, `[-5, 9, -12]` encoded as float32 big-endian bytes is `wKAAAEEQAADBQAAA`. ```console From 3aa90cf5a7e9fe9b1eab564db3bb741661cadc10 Mon Sep 17 00:00:00 2001 From: Aireza Heidarikhazaei Date: Fri, 27 Feb 2026 12:26:56 -0800 Subject: [PATCH 11/11] Clarifies kNN query vector input formats in docs Improves documentation by explicitly listing supported input formats for the kNN retriever and query APIs. Enhances clarity on when to use array, hex, or base64-encoded vectors and the applicable product versions for each format. --- .../elasticsearch/rest-apis/retrievers/knn-retriever.md | 6 ++++-- .../query-languages/query-dsl/query-dsl-knn-query.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md index 6620cda25b428..75120175b9cdf 100644 --- a/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md +++ b/docs/reference/elasticsearch/rest-apis/retrievers/knn-retriever.md @@ -21,8 +21,10 @@ A kNN retriever returns top documents from a [k-nearest neighbor search (kNN)](d : (Required if `query_vector_builder` is not defined, array of `float` or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). - Must be either an array of floats, a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions), {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` or a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. + Must be one of: + - An array of floats + - A hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` + - A base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` `query_vector_builder` diff --git a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md index cd290de2d749d..50248c8d1ce99 100644 --- a/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md +++ b/docs/reference/query-languages/query-dsl/query-dsl-knn-query.md @@ -109,8 +109,10 @@ PUT my-image-index `query_vector` : (Optional, array of floats or string) Query vector. Must have the same number of dimensions as the vector field you are searching against. - Must be either an array of floats or a hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` - It can also be a base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` + Must be one of: + - An array of floats + - A hex-encoded byte vector (one byte per dimension; for `bit`, one byte per 8 dimensions). {applies_to}`stack: ga 9.0-9.3` + - A base64-encoded vector string. Base64 supports `float` and `bfloat16` (big-endian), `byte`, and `bit` encodings depending on the target field type. {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` Either this or `query_vector_builder` must be provided.