ESQL: Document VALUES uniques (#128157)

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


---------

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

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

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).
 

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" : [

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

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/Values.java

@@ -72,9 +72,15 @@ 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 <<esql-mv_sort>>.",
+        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).""",
         appendix = """
+            ::::{tip}
+            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