Skip to content

Commit af1739b

Browse files
nik9000craigtaverner
nik9000
and
craigtaverner
authored
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 22f15e9 commit af1739b

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
@@ -110,11 +110,24 @@ It’s also possible to group by multiple values:
110110

111111
:::{include} ../examples/stats.csv-spec/statsGroupByMultipleValues.md
112112
:::
113+
113114
If all the grouping keys are multivalued then the input row is in all groups:
114115

115116
:::{include} ../examples/stats.csv-spec/multi-mv-group.md
116117
:::
117118

119+
The input **ROW** is in all groups. The entire row. All the values. Even group
120+
keys. That means that:
121+
122+
:::{include} ../examples/stats.csv-spec/mv-group-values.md
123+
:::
124+
125+
The `VALUES` function above sees the whole row - all of the values of the group
126+
key. If you want to send the group key to the function then `MV_EXPAND` first:
127+
128+
:::{include} ../examples/stats.csv-spec/mv-group-values-expand.md
129+
:::
130+
118131
Both the aggregating functions and the grouping expressions accept other
119132
functions. This is useful for using `STATS` on multivalue columns.
120133
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
@@ -2299,34 +2299,6 @@ M
22992299
null
23002300
;
23012301

2302-
docsStatsMvGroup
2303-
// tag::mv-group[]
2304-
ROW i=1, a=["a", "b"] | STATS MIN(i) BY a | SORT a ASC
2305-
// end::mv-group[]
2306-
;
2307-
2308-
// tag::mv-group-result[]
2309-
MIN(i):integer | a:keyword
2310-
1 | a
2311-
1 | b
2312-
// end::mv-group-result[]
2313-
;
2314-
2315-
docsStatsMultiMvGroup
2316-
// tag::multi-mv-group[]
2317-
ROW i=1, a=["a", "b"], b=[2, 3] | STATS MIN(i) BY a, b | SORT a ASC, b ASC
2318-
// end::multi-mv-group[]
2319-
;
2320-
2321-
// tag::multi-mv-group-result[]
2322-
MIN(i):integer | a:keyword | b:integer
2323-
1 | a | 2
2324-
1 | a | 3
2325-
1 | b | 2
2326-
1 | b | 3
2327-
// end::multi-mv-group-result[]
2328-
;
2329-
23302302
statsByConstant#[skip:-8.14.1,reason:implemented in 8.14]
23312303
from employees
23322304
| stats m = max(salary), a = round(avg(salary)) by 0
@@ -3338,3 +3310,74 @@ FROM employees
33383310
min1:integer | min2:integer | max1:integer | max2:integer
33393311
10011 | [10011, 10012] | 10079 | [10079, 10078]
33403312
;
3313+
3314+
sumRowMany
3315+
// tag::mv-group[]
3316+
ROW price = 10, color = ["blue", "pink", "yellow"]
3317+
| STATS SUM(price) BY color
3318+
// end::mv-group[]
3319+
| SORT color ASC
3320+
;
3321+
3322+
// tag::mv-group-result[]
3323+
SUM(price):long | color:keyword
3324+
10 | blue
3325+
10 | pink
3326+
10 | yellow
3327+
// end::mv-group-result[]
3328+
;
3329+
3330+
sumRowManyTwo
3331+
// tag::multi-mv-group[]
3332+
ROW price = 10, color = ["blue", "pink", "yellow"], size = ["s", "m", "l"]
3333+
| STATS SUM(price) BY color, size
3334+
// end::multi-mv-group[]
3335+
| SORT color ASC, size ASC
3336+
;
3337+
3338+
// tag::multi-mv-group-result[]
3339+
SUM(price):long | color:keyword | size:keyword
3340+
10 | blue | l
3341+
10 | blue | m
3342+
10 | blue | s
3343+
10 | pink | l
3344+
10 | pink | m
3345+
10 | pink | s
3346+
10 | yellow | l
3347+
10 | yellow | m
3348+
10 | yellow | s
3349+
// end::multi-mv-group-result[]
3350+
;
3351+
3352+
valuesRowMany
3353+
// tag::mv-group-values[]
3354+
ROW color = ["blue", "pink", "yellow"]
3355+
| STATS VALUES(color) BY color
3356+
// end::mv-group-values[]
3357+
| SORT color ASC
3358+
;
3359+
3360+
// tag::mv-group-values-result[]
3361+
VALUES(color):keyword | color:keyword
3362+
[blue, pink, yellow] | blue
3363+
[blue, pink, yellow] | pink
3364+
[blue, pink, yellow] | yellow
3365+
// end::mv-group-values-result[]
3366+
;
3367+
3368+
valuesRowManyExpand
3369+
// tag::mv-group-values-expand[]
3370+
ROW color = ["blue", "pink", "yellow"]
3371+
| MV_EXPAND color
3372+
| STATS VALUES(color) BY color
3373+
// end::mv-group-values-expand[]
3374+
| SORT color ASC
3375+
;
3376+
3377+
// tag::mv-group-values-expand-result[]
3378+
VALUES(color):keyword | color:keyword
3379+
blue | blue
3380+
pink | pink
3381+
yellow | yellow
3382+
// end::mv-group-values-expand-result[]
3383+
;

0 commit comments

Comments
 (0)