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/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/_snippets/lists/dense-vector-functions.md b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md new file mode 100644 index 0000000000000..3b54078e40bf2 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/lists/dense-vector-functions.md @@ -0,0 +1,8 @@ +* {applies_to}`stack: preview 9.2` {applies_to}`serverless: preview` [`KNN`](../../functions-operators/dense-vector-functions.md#esql-knn) + +% * {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 bf24c72108216..d77a7b3d1c7b5 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} Dense vector functions +:open: +:::{include} _snippets/lists/dense-vector-functions.md +::: +:::: + ::::{dropdown} Multi value functions :open: :::{include} _snippets/lists/mv-functions.md 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 new file mode 100644 index 0000000000000..d384eacc63a0d --- /dev/null +++ b/docs/reference/query-languages/esql/functions-operators/dense-vector-functions.md @@ -0,0 +1,60 @@ +--- +applies_to: + stack: preview + serverless: preview +navigation_title: "Dense vector functions" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-functions-operators.html#esql-dense-vector-functions +--- + +# {{esql}} dense vector functions [esql-dense-vector-functions] + +{{esql}} supports dense vector functions for vector similarity calculations and +k-nearest neighbor search. +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: + +:::{include} ../_snippets/lists/dense-vector-functions.md +::: + +:::{include} ../_snippets/functions/layout/knn.md +::: + +% V_COSINE is currently a hidden feature +% To make it visible again, uncomment this and the line in +% 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/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/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/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/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/dense-vector-functions.md +% :::{include} ../_snippets/functions/layout/v_magnitude.md +% ::: 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..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,12 +14,12 @@ 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). -::: -{{esql}} provides a set of functions for performing searching on text fields. +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. +::: -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 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/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index af4a657512dcb..c7f302127f789 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/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 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..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) } + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.2.0") } ) public Knn( Source source, @@ -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 ) {