From 0946c62f49452839a430e6ff4b8951284fa9f9a2 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 12:56:36 +0200 Subject: [PATCH 01/16] Add a section for vector functions in the doc. --- .../esql/_snippets/lists/vector-functions.md | 7 +++ .../esql/esql-functions-operators.md | 6 +++ .../functions-operators/vector-functions.md | 48 +++++++++++++++++++ 3 files changed, 61 insertions(+) create mode 100644 docs/reference/query-languages/esql/_snippets/lists/vector-functions.md create mode 100644 docs/reference/query-languages/esql/functions-operators/vector-functions.md diff --git a/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md new file mode 100644 index 0000000000000..90f3e8659eefd --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md @@ -0,0 +1,7 @@ +* <> +* <> +* <> +* <> +* <> +* <> +* <> \ No newline at end of file diff --git a/docs/reference/query-languages/esql/esql-functions-operators.md b/docs/reference/query-languages/esql/esql-functions-operators.md index bf24c72108216..0516b5c905f6d 100644 --- a/docs/reference/query-languages/esql/esql-functions-operators.md +++ b/docs/reference/query-languages/esql/esql-functions-operators.md @@ -80,6 +80,12 @@ mapped_pages: ::: :::: +::::{dropdown} Vector functions +:open: +:::{include} _snippets/lists/vector-functions.md +::: +:::: + ::::{dropdown} Multi value functions :open: :::{include} _snippets/lists/mv-functions.md diff --git a/docs/reference/query-languages/esql/functions-operators/vector-functions.md b/docs/reference/query-languages/esql/functions-operators/vector-functions.md new file mode 100644 index 0000000000000..1158355d32d55 --- /dev/null +++ b/docs/reference/query-languages/esql/functions-operators/vector-functions.md @@ -0,0 +1,48 @@ +--- +applies_to: + stack: preview + serverless: preview +navigation_title: "Vector functions" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-functions-operators.html#esql-vector-functions +--- + +# {{esql}} vector functions [esql-vector-functions] + +{{esql}} supports vector functions for dense vector similarity calculations and k-nearest neighbor search. + +These functions are primarily used for: +- Computing similarity between dense vectors using various similarity metrics +- Finding the k-nearest neighbors in vector space +- Calculating vector magnitudes and norms + +:::{note} +Vector functions are currently in **preview** and may change in future versions. +They work with `dense_vector` fields and require appropriate field mappings. +::: + +{{esql}} supports these vector functions: + +:::{include} ../_snippets/lists/vector-functions.md +::: + +:::{include} ../_snippets/functions/layout/knn.md +::: + +:::{include} ../_snippets/functions/layout/v_cosine.md +::: + +:::{include} ../_snippets/functions/layout/v_dot_product.md +::: + +:::{include} ../_snippets/functions/layout/v_hamming.md +::: + +:::{include} ../_snippets/functions/layout/v_l1_norm.md +::: + +:::{include} ../_snippets/functions/layout/v_l2_norm.md +::: + +:::{include} ../_snippets/functions/layout/v_magnitude.md +::: \ No newline at end of file From 94f33f1948a9a56ad590156b2ec92d55323a4109 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 13:02:34 +0200 Subject: [PATCH 02/16] Add vector functions to the TOC --- docs/reference/query-languages/toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index af4a657512dcb..4615fa2c00076 100644 --- a/docs/reference/query-languages/toc.yml +++ b/docs/reference/query-languages/toc.yml @@ -133,6 +133,7 @@ toc: - file: esql/functions-operators/search-functions.md - file: esql/functions-operators/spatial-functions.md - file: esql/functions-operators/string-functions.md + - file: esql/functions-operators/vector-functions.md - file: esql/functions-operators/type-conversion-functions.md - file: esql/functions-operators/mv-functions.md - file: esql/functions-operators/operators.md From 3bccdd55cf9685b5b21f729419c2897a49f8fcd8 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 16:16:20 +0200 Subject: [PATCH 03/16] Hiding snapshot functions. --- .../esql/_snippets/lists/vector-functions.md | 14 ++--- .../functions-operators/search-functions.md | 3 + .../functions-operators/vector-functions.md | 59 +++++++++++-------- 3 files changed, 46 insertions(+), 30 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md index 90f3e8659eefd..f67318657686d 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md @@ -1,7 +1,7 @@ -* <> -* <> -* <> -* <> -* <> -* <> -* <> \ No newline at end of file +* [`KNN`](../../functions-operators/vector-functions.md#esql-knn) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/vector-functions.md#esql-v_cosine) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/vector-functions.md#esql-v_dot_product) +% * {applies_to}`stack: preview` {applies_to}`serverless: preview` [`V_HAMMING`](../../functions-operators/vector-functions.md#esql-v_hamming) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/vector-functions.md#esql-v_l1_norm) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/vector-functions.md#esql-v_l2_norm) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/vector-functions.md#esql-v_magnitude) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/functions-operators/search-functions.md b/docs/reference/query-languages/esql/functions-operators/search-functions.md index 1360a9455c10c..17aa58c7bf362 100644 --- a/docs/reference/query-languages/esql/functions-operators/search-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/search-functions.md @@ -43,6 +43,9 @@ for information on the limitations of full text search. :::{include} ../_snippets/functions/layout/kql.md ::: +:::{include} ../_snippets/functions/layout/knn.md +::: + :::{include} ../_snippets/functions/layout/match.md ::: diff --git a/docs/reference/query-languages/esql/functions-operators/vector-functions.md b/docs/reference/query-languages/esql/functions-operators/vector-functions.md index 1158355d32d55..e4b2ea865ddfb 100644 --- a/docs/reference/query-languages/esql/functions-operators/vector-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/vector-functions.md @@ -11,13 +11,8 @@ mapped_pages: {{esql}} supports vector functions for dense vector similarity calculations and k-nearest neighbor search. -These functions are primarily used for: -- Computing similarity between dense vectors using various similarity metrics -- Finding the k-nearest neighbors in vector space -- Calculating vector magnitudes and norms - :::{note} -Vector functions are currently in **preview** and may change in future versions. +Vector functions are currently in **preview** and may change in future versions. They work with `dense_vector` fields and require appropriate field mappings. ::: @@ -29,20 +24,38 @@ They work with `dense_vector` fields and require appropriate field mappings. :::{include} ../_snippets/functions/layout/knn.md ::: -:::{include} ../_snippets/functions/layout/v_cosine.md -::: - -:::{include} ../_snippets/functions/layout/v_dot_product.md -::: - -:::{include} ../_snippets/functions/layout/v_hamming.md -::: - -:::{include} ../_snippets/functions/layout/v_l1_norm.md -::: - -:::{include} ../_snippets/functions/layout/v_l2_norm.md -::: - -:::{include} ../_snippets/functions/layout/v_magnitude.md -::: \ No newline at end of file +% V_COSINE is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_cosine.md +% ::: + +% V_DOT_PRODUCT is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_dot_product.md +% ::: + +% V_HAMMING is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_hamming.md +% ::: + +% V_L1_NORM is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_l1_norm.md +% ::: + +% V_L2_NORM is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_l2_norm.md +% ::: + +% V_MAGNITUDE is currently a hidden feature +% To make it visible again, uncomment this and the line in +% lists/vector-functions.md +% :::{include} ../_snippets/functions/layout/v_magnitude.md +% ::: From 98afbffeb8af2575a7f0579faaeeeef671bcf7eb Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 16:41:12 +0200 Subject: [PATCH 04/16] Fix KNN docs --- .../esql/_snippets/functions/parameters/knn.md | 2 +- .../query-languages/esql/kibana/definition/functions/knn.json | 4 ++-- .../xpack/esql/expression/function/vector/Knn.java | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/parameters/knn.md b/docs/reference/query-languages/esql/_snippets/functions/parameters/knn.md index 0a234d119fac0..e7316f85103a6 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/parameters/knn.md +++ b/docs/reference/query-languages/esql/_snippets/functions/parameters/knn.md @@ -9,5 +9,5 @@ : Vector value to find top nearest neighbours for. `options` -: (Optional) kNN additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [knn query](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-knn-query) for more information. +: (Optional) kNN additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [knn query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) for more information. diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/knn.json b/docs/reference/query-languages/esql/kibana/definition/functions/knn.json index 5aa44b7917eb6..aeb1c492bcba1 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/knn.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/knn.json @@ -23,7 +23,7 @@ "type" : "function_named_parameters", "mapParams" : "{name='boost', values=[2.5], description='Floating point number used to decrease or increase the relevance scores of the query.Defaults to 1.0.'}, {name='min_candidates', values=[10], description='The minimum number of nearest neighbor candidates to consider per shard while doing knn search. KNN may use a higher number of candidates in case the query can't use a approximate results. Cannot exceed 10,000. Increasing min_candidates tends to improve the accuracy of the final results. Defaults to 1.5 * LIMIT used for the query.'}, {name='rescore_oversample', values=[3.5], description='Applies the specified oversampling for rescoring quantized vectors. See [oversampling and rescoring quantized vectors](docs-content://solutions/search/vector/knn.md#dense-vector-knn-search-rescoring) for details.'}, {name='similarity', values=[0.01], description='The minimum similarity required for a document to be considered a match. The similarity value calculated relates to the raw similarity used, not the document score.'}", "optional" : true, - "description" : "(Optional) kNN additional options as <>. See <> for more information." + "description" : "(Optional) kNN additional options as <>. See [knn query](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-knn-query) for more information." } ], "variadic" : false, @@ -48,7 +48,7 @@ "type" : "function_named_parameters", "mapParams" : "{name='boost', values=[2.5], description='Floating point number used to decrease or increase the relevance scores of the query.Defaults to 1.0.'}, {name='min_candidates', values=[10], description='The minimum number of nearest neighbor candidates to consider per shard while doing knn search. KNN may use a higher number of candidates in case the query can't use a approximate results. Cannot exceed 10,000. Increasing min_candidates tends to improve the accuracy of the final results. Defaults to 1.5 * LIMIT used for the query.'}, {name='rescore_oversample', values=[3.5], description='Applies the specified oversampling for rescoring quantized vectors. See [oversampling and rescoring quantized vectors](docs-content://solutions/search/vector/knn.md#dense-vector-knn-search-rescoring) for details.'}, {name='similarity', values=[0.01], description='The minimum similarity required for a document to be considered a match. The similarity value calculated relates to the raw similarity used, not the document score.'}", "optional" : true, - "description" : "(Optional) kNN additional options as <>. See <> for more information." + "description" : "(Optional) kNN additional options as <>. See [knn query](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-knn-query) for more information." } ], "variadic" : false, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java index 8588bbffaf0f0..bf8c5bd45cd71 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java @@ -153,7 +153,7 @@ public Knn( + "(docs-content://solutions/search/vector/knn.md#dense-vector-knn-search-rescoring) for details." ), }, description = "(Optional) kNN additional options as <>." - + " See <> for more information.", + + " See [knn query](/reference/query-languages/query-dsl/query-dsl-knn-query.md) for more information.", optional = true ) Expression options ) { From b0d610679e8a90a571145a629ba64dfec1432e73 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 16:46:38 +0200 Subject: [PATCH 05/16] Remove KNN from search functions. --- .../esql/functions-operators/search-functions.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/reference/query-languages/esql/functions-operators/search-functions.md b/docs/reference/query-languages/esql/functions-operators/search-functions.md index 17aa58c7bf362..1360a9455c10c 100644 --- a/docs/reference/query-languages/esql/functions-operators/search-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/search-functions.md @@ -43,9 +43,6 @@ for information on the limitations of full text search. :::{include} ../_snippets/functions/layout/kql.md ::: -:::{include} ../_snippets/functions/layout/knn.md -::: - :::{include} ../_snippets/functions/layout/match.md ::: From 7c814f216637860b57c7965258497e250503f37b Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 16:53:56 +0200 Subject: [PATCH 06/16] Renamed vector functions into dense vector functions --- .../_snippets/lists/dense-vector-functions.md | 13 ++++++++++ .../esql/_snippets/lists/vector-functions.md | 7 ----- .../esql/esql-functions-operators.md | 2 +- ...functions.md => dense-vector-functions.md} | 26 ++++++++++--------- docs/reference/query-languages/toc.yml | 2 +- 5 files changed, 29 insertions(+), 21 deletions(-) create mode 100644 docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md delete mode 100644 docs/reference/query-languages/esql/_snippets/lists/vector-functions.md rename docs/reference/query-languages/esql/functions-operators/{vector-functions.md => dense-vector-functions.md} (68%) diff --git a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md new file mode 100644 index 0000000000000..a54c8f40a4004 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -0,0 +1,13 @@ +* [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) + % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + `V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) + % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + `V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) + % * {applies_to}`stack: preview` {applies_to}`serverless: preview` [ + `V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) + % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + `V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) + % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + `V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) + % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + `V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) diff --git a/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md deleted file mode 100644 index f67318657686d..0000000000000 --- a/docs/reference/query-languages/esql/_snippets/lists/vector-functions.md +++ /dev/null @@ -1,7 +0,0 @@ -* [`KNN`](../../functions-operators/vector-functions.md#esql-knn) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/vector-functions.md#esql-v_cosine) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/vector-functions.md#esql-v_dot_product) -% * {applies_to}`stack: preview` {applies_to}`serverless: preview` [`V_HAMMING`](../../functions-operators/vector-functions.md#esql-v_hamming) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/vector-functions.md#esql-v_l1_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/vector-functions.md#esql-v_l2_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/vector-functions.md#esql-v_magnitude) \ No newline at end of file diff --git a/docs/reference/query-languages/esql/esql-functions-operators.md b/docs/reference/query-languages/esql/esql-functions-operators.md index 0516b5c905f6d..f53ab1335c600 100644 --- a/docs/reference/query-languages/esql/esql-functions-operators.md +++ b/docs/reference/query-languages/esql/esql-functions-operators.md @@ -82,7 +82,7 @@ mapped_pages: ::::{dropdown} Vector functions :open: -:::{include} _snippets/lists/vector-functions.md +:::{include} _snippets/lists/dense-vector-functions.md ::: :::: diff --git a/docs/reference/query-languages/esql/functions-operators/vector-functions.md b/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md similarity index 68% rename from docs/reference/query-languages/esql/functions-operators/vector-functions.md rename to docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md index e4b2ea865ddfb..c9c3ea1e07f12 100644 --- a/docs/reference/query-languages/esql/functions-operators/vector-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md @@ -2,23 +2,25 @@ applies_to: stack: preview serverless: preview -navigation_title: "Vector functions" +navigation_title: "Dense vector functions" mapped_pages: - - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-functions-operators.html#esql-vector-functions + - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-functions-operators.html#esql-dense-vector-functions --- -# {{esql}} vector functions [esql-vector-functions] +# {{esql}} dense vector functions [esql-dense-vector-functions] -{{esql}} supports vector functions for dense vector similarity calculations and k-nearest neighbor search. +{{esql}} supports dense vector functions for vector similarity calculations and +k-nearest neighbor search. :::{note} -Vector functions are currently in **preview** and may change in future versions. +Dense vector functions are currently in **preview** and may change in future +versions. They work with `dense_vector` fields and require appropriate field mappings. ::: {{esql}} supports these vector functions: -:::{include} ../_snippets/lists/vector-functions.md +:::{include} ../_snippets/lists/dense-vector-functions.md ::: :::{include} ../_snippets/functions/layout/knn.md @@ -26,36 +28,36 @@ They work with `dense_vector` fields and require appropriate field mappings. % V_COSINE is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_cosine.md % ::: % V_DOT_PRODUCT is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_dot_product.md % ::: % V_HAMMING is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_hamming.md % ::: % V_L1_NORM is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_l1_norm.md % ::: % V_L2_NORM is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_l2_norm.md % ::: % V_MAGNITUDE is currently a hidden feature % To make it visible again, uncomment this and the line in -% lists/vector-functions.md +% lists/dense-vector-functions.md % :::{include} ../_snippets/functions/layout/v_magnitude.md % ::: diff --git a/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index 4615fa2c00076..fc0ed9c47bea4 100644 --- a/docs/reference/query-languages/toc.yml +++ b/docs/reference/query-languages/toc.yml @@ -133,7 +133,7 @@ toc: - file: esql/functions-operators/search-functions.md - file: esql/functions-operators/spatial-functions.md - file: esql/functions-operators/string-functions.md - - file: esql/functions-operators/vector-functions.md + - file: esql/functions-operators/dense-dense-vector-functions.md - file: esql/functions-operators/type-conversion-functions.md - file: esql/functions-operators/mv-functions.md - file: esql/functions-operators/operators.md From b7d6732bdef481dfa3fa7b052deb3dc660c28b5d Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 16:56:33 +0200 Subject: [PATCH 07/16] Fix typo in toc --- docs/reference/query-languages/toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index fc0ed9c47bea4..c7f302127f789 100644 --- a/docs/reference/query-languages/toc.yml +++ b/docs/reference/query-languages/toc.yml @@ -133,7 +133,7 @@ toc: - file: esql/functions-operators/search-functions.md - file: esql/functions-operators/spatial-functions.md - file: esql/functions-operators/string-functions.md - - file: esql/functions-operators/dense-dense-vector-functions.md + - file: esql/functions-operators/dense-vector-functions.md - file: esql/functions-operators/type-conversion-functions.md - file: esql/functions-operators/mv-functions.md - file: esql/functions-operators/operators.md From 53af9e8d55fbf36053b87436748e3721a4adc376 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:02:42 +0200 Subject: [PATCH 08/16] Appy suggestion from review. --- .../esql/functions-operators/dense-vector-functions.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md b/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md index c9c3ea1e07f12..d384eacc63a0d 100644 --- a/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md @@ -11,12 +11,9 @@ mapped_pages: {{esql}} supports dense vector functions for vector similarity calculations and k-nearest neighbor search. - -:::{note} -Dense vector functions are currently in **preview** and may change in future -versions. -They work with `dense_vector` fields and require appropriate field mappings. -::: +Dsense vector functions work with [ +`dense_vector` fields](/reference/elasticsearch/mapping-reference/dense-vector.md) +and require appropriate field mappings. {{esql}} supports these vector functions: From 18652e3f5c45d4263882239bfd42f11eb5f55a44 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:10:59 +0200 Subject: [PATCH 09/16] Add a link to dense vector function in the search functions section. --- .../esql/functions-operators/search-functions.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/reference/query-languages/esql/functions-operators/search-functions.md b/docs/reference/query-languages/esql/functions-operators/search-functions.md index 1360a9455c10c..b5842f58a035b 100644 --- a/docs/reference/query-languages/esql/functions-operators/search-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/search-functions.md @@ -16,10 +16,6 @@ our [hands-on tutorial](/reference/query-languages/esql/esql-search-tutorial.md) For a high-level overview of search functionalities in {{esql}}, and to learn about relevance scoring, refer to [{{esql}} for search](docs-content://solutions/search/esql-for-search.md#esql-for-search-scoring). ::: -{{esql}} provides a set of functions for performing searching on text fields. - -Use these functions -for [full-text search](docs-content://solutions/search/full-text.md) and [semantic search](docs-content://solutions/search/semantic-search/semantic-search-semantic-text.md). Full text functions can be used to @@ -27,6 +23,12 @@ match [multivalued fields](/reference/query-languages/esql/esql-multivalued-fiel A multivalued field that contains a value that matches a full text query is considered to match the query. +:::{tip} +For information regarding dense vector search functions, +including [KNN](dense-vector-functions.md#esql-knn), please refer to +the [Dense vector functions](dense-vector-functions.md) documentation. +::: + Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with `LIKE` or `RLIKE`. From 2cb911893999ee0ea421540b30e9880f3b1806e2 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:13:45 +0200 Subject: [PATCH 10/16] Modify the link to dense vector functions in the search function section. --- .../esql/functions-operators/search-functions.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/reference/query-languages/esql/functions-operators/search-functions.md b/docs/reference/query-languages/esql/functions-operators/search-functions.md index b5842f58a035b..1e3bfc8986e1b 100644 --- a/docs/reference/query-languages/esql/functions-operators/search-functions.md +++ b/docs/reference/query-languages/esql/functions-operators/search-functions.md @@ -14,6 +14,10 @@ Get started with {{esql}} for search use cases with our [hands-on tutorial](/reference/query-languages/esql/esql-search-tutorial.md). For a high-level overview of search functionalities in {{esql}}, and to learn about relevance scoring, refer to [{{esql}} for search](docs-content://solutions/search/esql-for-search.md#esql-for-search-scoring). + +For information regarding dense vector search functions, +including [KNN](dense-vector-functions.md#esql-knn), please refer to +the [Dense vector functions](dense-vector-functions.md) documentation. ::: and [semantic search](docs-content://solutions/search/semantic-search/semantic-search-semantic-text.md). @@ -23,12 +27,6 @@ match [multivalued fields](/reference/query-languages/esql/esql-multivalued-fiel A multivalued field that contains a value that matches a full text query is considered to match the query. -:::{tip} -For information regarding dense vector search functions, -including [KNN](dense-vector-functions.md#esql-knn), please refer to -the [Dense vector functions](dense-vector-functions.md) documentation. -::: - Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with `LIKE` or `RLIKE`. From 86c7df66d28591badc1a37c0ba4a4bc31beac537 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:15:21 +0200 Subject: [PATCH 11/16] Try to fix dense vectors function list. --- .../esql/_snippets/lists/dense-vector-functions.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md index a54c8f40a4004..1112919da113e 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -1,13 +1,14 @@ * [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) - % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ + +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ `V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) - % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ `V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) - % * {applies_to}`stack: preview` {applies_to}`serverless: preview` [ +% * {applies_to}`stack: preview` {applies_to}`serverless: preview` [ `V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) - % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ `V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) - % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ `V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) - % * {applies_to}`stack: development` {applies_to}`serverless: preview` [ +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ `V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) From 1c160504c13b6fc3bdd08d3abcea717e21d36116 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:23:43 +0200 Subject: [PATCH 12/16] Fix newlines in the code. --- .../_snippets/lists/dense-vector-functions.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md index 1112919da113e..08719fcb5dd49 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -1,14 +1,8 @@ * [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ - `V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ - `V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) -% * {applies_to}`stack: preview` {applies_to}`serverless: preview` [ - `V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ - `V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ - `V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [ - `V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) +% * {applies_to}`stack: preview` {applies_to}`serverless: preview`[`V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) +% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) From d9ec999c8de83e5c71b4553183b82945c94b1028 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:28:40 +0200 Subject: [PATCH 13/16] Set specific version for unreleased vector functions (can be revisited when we will be uncommenting them --- .../esql/_snippets/lists/dense-vector-functions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md index 08719fcb5dd49..99fbec7c46f32 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -1,8 +1,8 @@ * [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) -% * {applies_to}`stack: preview` {applies_to}`serverless: preview`[`V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) -% * {applies_to}`stack: development` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview`[`V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) +% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) From e25ebac262e061176fe65c8e112d2bbd5540dad2 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:32:14 +0200 Subject: [PATCH 14/16] Fix versioning of the KNN function. --- .../xpack/esql/expression/function/vector/Knn.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java index bf8c5bd45cd71..11e5e58c9defa 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java @@ -103,7 +103,7 @@ public class Knn extends FullTextFunction description = "Finds the k nearest vectors to a query vector, as measured by a similarity metric. " + "knn function finds nearest vectors through approximate search on indexed dense_vectors or semantic_text fields.", examples = { @Example(file = "knn-function", tag = "knn-function") }, - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW) } + appliesTo = {@FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0")} ) public Knn( Source source, From 391c6a01cbd669075bafd9d1ebc1d845c44b9457 Mon Sep 17 00:00:00 2001 From: afoucret Date: Tue, 7 Oct 2025 17:37:54 +0200 Subject: [PATCH 15/16] Improved versioning --- .../esql/_snippets/functions/layout/knn.md | 2 +- .../esql/_snippets/lists/dense-vector-functions.md | 14 +++++++------- .../esql/esql-functions-operators.md | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/knn.md b/docs/reference/query-languages/esql/_snippets/functions/layout/knn.md index c834b317bcd3f..34c9207d04f5c 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/knn.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/knn.md @@ -2,7 +2,7 @@ ## `KNN` [esql-knn] ```{applies_to} -stack: preview +stack: preview 9.2.0 serverless: preview ``` diff --git a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md index 99fbec7c46f32..3b54078e40bf2 100644 --- a/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -1,8 +1,8 @@ -* [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview`[`V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) -% * {applies_to}`stack: 9.3` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview` [`V_COSINE`](../../functions-operators/dense-vector-functions.md#esql-v_cosine) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview` [`V_DOT_PRODUCT`](../../functions-operators/dense-vector-functions.md#esql-v_dot_product) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview`[`V_HAMMING`](../../functions-operators/dense-vector-functions.md#esql-v_hamming) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview` [`V_L1_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l1_norm) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview` [`V_L2_NORM`](../../functions-operators/dense-vector-functions.md#esql-v_l2_norm) +% * {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview` [`V_MAGNITUDE`](../../functions-operators/dense-vector-functions.md#esql-v_magnitude) diff --git a/docs/reference/query-languages/esql/esql-functions-operators.md b/docs/reference/query-languages/esql/esql-functions-operators.md index f53ab1335c600..d77a7b3d1c7b5 100644 --- a/docs/reference/query-languages/esql/esql-functions-operators.md +++ b/docs/reference/query-languages/esql/esql-functions-operators.md @@ -80,7 +80,7 @@ mapped_pages: ::: :::: -::::{dropdown} Vector functions +::::{dropdown} Dense vector functions :open: :::{include} _snippets/lists/dense-vector-functions.md ::: From 926f4905a68dc914f5165aacb50eb2868acdcd8e Mon Sep 17 00:00:00 2001 From: elasticsearchmachine Date: Tue, 7 Oct 2025 15:45:39 +0000 Subject: [PATCH 16/16] [CI] Auto commit changes from spotless --- .../xpack/esql/expression/function/vector/Knn.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java index 11e5e58c9defa..537c9a8080f25 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/vector/Knn.java @@ -103,7 +103,7 @@ public class Knn extends FullTextFunction description = "Finds the k nearest vectors to a query vector, as measured by a similarity metric. " + "knn function finds nearest vectors through approximate search on indexed dense_vectors or semantic_text fields.", examples = { @Example(file = "knn-function", tag = "knn-function") }, - appliesTo = {@FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0")} + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") } ) public Knn( Source source,