Skip to content

Commit 09cf70d

Browse files
nik9000craigtaverner
nik9000
and
craigtaverner
committed
Better explain STATS on multivalued fields (#135109)
Updates the docs for multivalued fields to make it clear that grouping puts the entire *row* in each group. Relates to #134792 Co-authored-by: Craig Taverner <[email protected]>
1 parent 16cc527 commit 09cf70d

File tree

6 files changed

+127
-38
lines changed

6 files changed

+127
-38
lines changed

‎docs/reference/query-languages/esql/_snippets/commands/examples/stats.csv-spec/multi-mv-group.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
22

33
```esql
4-
ROW i=1, a=["a", "b"], b=[2, 3] | STATS MIN(i) BY a, b | SORT a ASC, b ASC
4+
ROW price = 10, color = ["blue", "pink", "yellow"], size = ["s", "m", "l"]
5+
| STATS SUM(price) BY color, size
56
```
67

7-
| MIN(i):integer | a:keyword | b:integer |
8+
| SUM(price):long | color:keyword | size:keyword |
89
| --- | --- | --- |
9-
| 1 | a | 2 |
10-
| 1 | a | 3 |
11-
| 1 | b | 2 |
12-
| 1 | b | 3 |
10+
| 10 | blue | l |
11+
| 10 | blue | m |
12+
| 10 | blue | s |
13+
| 10 | pink | l |
14+
| 10 | pink | m |
15+
| 10 | pink | s |
16+
| 10 | yellow | l |
17+
| 10 | yellow | m |
18+
| 10 | yellow | s |

‎docs/reference/query-languages/esql/_snippets/commands/examples/stats.csv-spec/mv-group-values-expand.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
ROW color = ["blue", "pink", "yellow"]
5+
| MV_EXPAND color
6+
| STATS VALUES(color) BY color
7+
```
8+
9+
| VALUES(color):keyword | color:keyword |
10+
| --- | --- |
11+
| blue | blue |
12+
| pink | pink |
13+
| yellow | yellow |

‎docs/reference/query-languages/esql/_snippets/commands/examples/stats.csv-spec/mv-group-values.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
ROW color = ["blue", "pink", "yellow"]
5+
| STATS VALUES(color) BY color
6+
```
7+
8+
| VALUES(color):keyword | color:keyword |
9+
| --- | --- |
10+
| [blue, pink, yellow] | blue |
11+
| [blue, pink, yellow] | pink |
12+
| [blue, pink, yellow] | yellow |

‎docs/reference/query-languages/esql/_snippets/commands/examples/stats.csv-spec/mv-group.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
22

33
```esql
4-
ROW i=1, a=["a", "b"] | STATS MIN(i) BY a | SORT a ASC
4+
ROW price = 10, color = ["blue", "pink", "yellow"]
5+
| STATS SUM(price) BY color
56
```
67

7-
| MIN(i):integer | a:keyword |
8+
| SUM(price):long | color:keyword |
89
| --- | --- |
9-
| 1 | a |
10-
| 1 | b |
10+
| 10 | blue |
11+
| 10 | pink |
12+
| 10 | yellow |

‎docs/reference/query-languages/esql/_snippets/commands/layout/stats-by.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,11 +107,24 @@ It’s also possible to group by multiple values:
107107

108108
:::{include} ../examples/stats.csv-spec/statsGroupByMultipleValues.md
109109
:::
110+
110111
If all the grouping keys are multivalued then the input row is in all groups:
111112

112113
:::{include} ../examples/stats.csv-spec/multi-mv-group.md
113114
:::
114115

116+
The input **ROW** is in all groups. The entire row. All the values. Even group
117+
keys. That means that:
118+
119+
:::{include} ../examples/stats.csv-spec/mv-group-values.md
120+
:::
121+
122+
The `VALUES` function above sees the whole row - all of the values of the group
123+
key. If you want to send the group key to the function then `MV_EXPAND` first:
124+
125+
:::{include} ../examples/stats.csv-spec/mv-group-values-expand.md
126+
:::
127+
115128
Both the aggregating functions and the grouping expressions accept other
116129
functions. This is useful for using `STATS` on multivalue columns.
117130
For example, to calculate the average salary change, you can use `MV_AVG` to

‎x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec‎

Lines changed: 71 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2275,34 +2275,6 @@ M
22752275
null
22762276
;
22772277

2278-
docsStatsMvGroup
2279-
// tag::mv-group[]
2280-
ROW i=1, a=["a", "b"] | STATS MIN(i) BY a | SORT a ASC
2281-
// end::mv-group[]
2282-
;
2283-
2284-
// tag::mv-group-result[]
2285-
MIN(i):integer | a:keyword
2286-
1 | a
2287-
1 | b
2288-
// end::mv-group-result[]
2289-
;
2290-
2291-
docsStatsMultiMvGroup
2292-
// tag::multi-mv-group[]
2293-
ROW i=1, a=["a", "b"], b=[2, 3] | STATS MIN(i) BY a, b | SORT a ASC, b ASC
2294-
// end::multi-mv-group[]
2295-
;
2296-
2297-
// tag::multi-mv-group-result[]
2298-
MIN(i):integer | a:keyword | b:integer
2299-
1 | a | 2
2300-
1 | a | 3
2301-
1 | b | 2
2302-
1 | b | 3
2303-
// end::multi-mv-group-result[]
2304-
;
2305-
23062278
statsByConstant#[skip:-8.14.1,reason:implemented in 8.14]
23072279
from employees
23082280
| stats m = max(salary), a = round(avg(salary)) by 0
@@ -3256,3 +3228,74 @@ FROM employees
32563228
min1:integer | min2:integer | max1:integer | max2:integer
32573229
10011 | [10011, 10012] | 10079 | [10079, 10078]
32583230
;
3231+
3232+
sumRowMany
3233+
// tag::mv-group[]
3234+
ROW price = 10, color = ["blue", "pink", "yellow"]
3235+
| STATS SUM(price) BY color
3236+
// end::mv-group[]
3237+
| SORT color ASC
3238+
;
3239+
3240+
// tag::mv-group-result[]
3241+
SUM(price):long | color:keyword
3242+
10 | blue
3243+
10 | pink
3244+
10 | yellow
3245+
// end::mv-group-result[]
3246+
;
3247+
3248+
sumRowManyTwo
3249+
// tag::multi-mv-group[]
3250+
ROW price = 10, color = ["blue", "pink", "yellow"], size = ["s", "m", "l"]
3251+
| STATS SUM(price) BY color, size
3252+
// end::multi-mv-group[]
3253+
| SORT color ASC, size ASC
3254+
;
3255+
3256+
// tag::multi-mv-group-result[]
3257+
SUM(price):long | color:keyword | size:keyword
3258+
10 | blue | l
3259+
10 | blue | m
3260+
10 | blue | s
3261+
10 | pink | l
3262+
10 | pink | m
3263+
10 | pink | s
3264+
10 | yellow | l
3265+
10 | yellow | m
3266+
10 | yellow | s
3267+
// end::multi-mv-group-result[]
3268+
;
3269+
3270+
valuesRowMany
3271+
// tag::mv-group-values[]
3272+
ROW color = ["blue", "pink", "yellow"]
3273+
| STATS VALUES(color) BY color
3274+
// end::mv-group-values[]
3275+
| SORT color ASC
3276+
;
3277+
3278+
// tag::mv-group-values-result[]
3279+
VALUES(color):keyword | color:keyword
3280+
[blue, pink, yellow] | blue
3281+
[blue, pink, yellow] | pink
3282+
[blue, pink, yellow] | yellow
3283+
// end::mv-group-values-result[]
3284+
;
3285+
3286+
valuesRowManyExpand
3287+
// tag::mv-group-values-expand[]
3288+
ROW color = ["blue", "pink", "yellow"]
3289+
| MV_EXPAND color
3290+
| STATS VALUES(color) BY color
3291+
// end::mv-group-values-expand[]
3292+
| SORT color ASC
3293+
;
3294+
3295+
// tag::mv-group-values-expand-result[]
3296+
VALUES(color):keyword | color:keyword
3297+
blue | blue
3298+
pink | pink
3299+
yellow | yellow
3300+
// end::mv-group-values-expand-result[]
3301+
;

0 commit comments

Comments
 (0)