From 00644f28bcf5d0d32d0a6d349a19a33d791130a2 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 19 May 2025 14:46:52 -0400 Subject: [PATCH 1/4] ESQL: Document VALUES uniques Documents that the VALUES aggregate function returns unique documents and points folks to the TOP aggregate function if they want to keep dupes. Closes #128091 --- .../esql/_snippets/functions/appendix/values.md | 3 +++ .../esql/_snippets/functions/description/values.md | 2 +- .../esql/kibana/definition/functions/values.json | 2 +- .../query-languages/esql/kibana/docs/functions/values.md | 3 ++- .../xpack/esql/expression/function/aggregate/Values.java | 8 ++++++-- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md b/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md index 5170ebd00674a..4a21c08c79756 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/appendix/values.md @@ -1,5 +1,8 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. +::::{note} +Use [`TOP`](/reference/query-languages/esql/functions-operators/aggregation-functions.md#esql-top) if you need to keep repeated values. +:::: ::::{warning} This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until diff --git a/docs/reference/query-languages/esql/_snippets/functions/description/values.md b/docs/reference/query-languages/esql/_snippets/functions/description/values.md index ecfd420f7c9da..b4ed8a87d77e4 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/description/values.md +++ b/docs/reference/query-languages/esql/_snippets/functions/description/values.md @@ -2,5 +2,5 @@ **Description** -Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort). +Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort). diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/values.json b/docs/reference/query-languages/esql/kibana/definition/functions/values.json index d64dc2143fe9c..7983f9d2b66ab 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/values.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/values.json @@ -2,7 +2,7 @@ "comment" : "This is generated by ESQL’s AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.", "type" : "agg", "name" : "values", - "description" : "Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use `MV_SORT`.", + "description" : "Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed.\nIf you need the values returned in order use `MV_SORT`.", "signatures" : [ { "params" : [ diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/values.md b/docs/reference/query-languages/esql/kibana/docs/functions/values.md index 830053a6a2ada..130c7f3d60e20 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/values.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/values.md @@ -1,7 +1,8 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ### VALUES -Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/mv-functions#esql-mv_sort). +Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. +If you need the values returned in order use [`MV_SORT`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/mv-functions#esql-mv_sort). ```esql FROM employees diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index e53d62aba725c..5f0ba75fff33f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -72,9 +72,13 @@ public class Values extends AggregateFunction implements ToAggregator { "long", "version" }, preview = true, - description = "Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. " - + "If you need the values returned in order use <>.", + description = """ + Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. + If you need the values returned in order use <>.""", appendix = """ + ::::{note} + Use <> if you need to keep repeated values. + :::: ::::{warning} This can use a significant amount of memory and ES|QL doesn’t yet grow aggregations beyond memory. So this aggregation will work until From bf9bbb7536442665e14ddf310443b370a5cf6a4e Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 21 May 2025 08:57:57 -0400 Subject: [PATCH 2/4] Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- .../xpack/esql/expression/function/aggregate/Values.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index 5f0ba75fff33f..c2e51c4cb382f 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -74,10 +74,10 @@ public class Values extends AggregateFunction implements ToAggregator { preview = true, description = """ Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. - If you need the values returned in order use <>.""", + If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort).""", appendix = """ ::::{note} - Use <> if you need to keep repeated values. + Use [`TOP`](/reference/query-languages/esql/functions-operators/aggregation-functions.md#esql-top) if you need to keep repeated values. :::: ::::{warning} This can use a significant amount of memory and ES|QL doesn’t yet From bc2c334bd559acb399134d2faf473f99a132c911 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 22 May 2025 08:39:39 -0400 Subject: [PATCH 3/4] Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- .../xpack/esql/expression/function/aggregate/Values.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/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index c2e51c4cb382f..6d33e3bfa4804 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -76,7 +76,7 @@ public class Values extends AggregateFunction implements ToAggregator { Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort).""", appendix = """ - ::::{note} + ::::{tip} Use [`TOP`](/reference/query-languages/esql/functions-operators/aggregation-functions.md#esql-top) if you need to keep repeated values. :::: ::::{warning} From 438a0953fac07c02c570d254b2e7791f3368162b Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 22 May 2025 08:42:07 -0400 Subject: [PATCH 4/4] format --- .../xpack/esql/expression/function/aggregate/Values.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java index 6d33e3bfa4804..721cdc0a55241 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java @@ -74,10 +74,12 @@ public class Values extends AggregateFunction implements ToAggregator { preview = true, description = """ Returns unique values as a multivalued field. The order of the returned values isn’t guaranteed. - If you need the values returned in order use [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort).""", + If you need the values returned in order use + [`MV_SORT`](/reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_sort).""", appendix = """ ::::{tip} - Use [`TOP`](/reference/query-languages/esql/functions-operators/aggregation-functions.md#esql-top) if you need to keep repeated values. + Use [`TOP`](/reference/query-languages/esql/functions-operators/aggregation-functions.md#esql-top) + if you need to keep repeated values. :::: ::::{warning} This can use a significant amount of memory and ES|QL doesn’t yet