Skip to content

Commit 3c0ac2b

Browse files
astefangmjehovich
astefan
authored and
gmjehovich
committed
ESQL: INLINESTATS docs (elastic#134480)
Fixes elastic#124718
1 parent dcf170e commit 3c0ac2b

File tree

13 files changed

+291
-124
lines changed

13 files changed

+291
-124
lines changed

‎docs/reference/query-languages/esql/_snippets/commands/examples/inlinestats.csv-spec/avg-salaries-where.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
FROM employees
5+
| KEEP emp_no, salary
6+
| INLINESTATS avg_lt_50 = ROUND(AVG(salary)) WHERE salary < 50000,
7+
avg_lt_60 = ROUND(AVG(salary)) WHERE salary >=50000 AND salary < 60000,
8+
avg_gt_60 = ROUND(AVG(salary)) WHERE salary >= 60000
9+
```
10+
11+
| emp_no:integer | salary:integer | avg_lt_50:double | avg_lt_60:double | avg_gt_60:double |
12+
| --- | --- | --- | --- | --- |
13+
| 10001 | 57305 | 38292.0 | 54221.0 | 67286.0 |
14+
| 10002 | 56371 | 38292.0 | 54221.0 | 67286.0 |
15+
| 10003 | 61805 | 38292.0 | 54221.0 | 67286.0 |
16+
| 10004 | 36174 | 38292.0 | 54221.0 | 67286.0 |
17+
| 10005 | 63528 | 38292.0 | 54221.0 | 67286.0 |

‎docs/reference/query-languages/esql/_snippets/commands/examples/inlinestats.csv-spec/max-salary-without-by.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
FROM employees
5+
| KEEP emp_no, languages, salary
6+
| INLINESTATS max_salary = MAX(salary)
7+
```
8+
9+
| emp_no:integer | languages:integer | salary:integer | max_salary:integer |
10+
| --- | --- | --- | --- |
11+
| 10001 | 2 | 57305 | 74999 |
12+
| 10002 | 5 | 56371 | 74999 |
13+
| 10003 | 4 | 61805 | 74999 |
14+
| 10004 | 5 | 36174 | 74999 |
15+
| 10005 | 1 | 63528 | 74999 |

‎docs/reference/query-languages/esql/_snippets/commands/examples/inlinestats.csv-spec/max-salary.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
FROM employees
5+
| KEEP emp_no, languages, salary
6+
| INLINESTATS max_salary = MAX(salary) BY languages
7+
```
8+
9+
| emp_no:integer | salary:integer | max_salary:integer | languages:integer |
10+
| --- | --- | --- | --- |
11+
| 10001 | 57305 | 73578 | 2 |
12+
| 10002 | 56371 | 66817 | 5 |
13+
| 10003 | 61805 | 74572 | 4 |
14+
| 10004 | 36174 | 66817 | 5 |
15+
| 10005 | 63528 | 73717 | 1 |

‎docs/reference/query-languages/esql/_snippets/commands/examples/inlinestats.csv-spec/multi-agg-multi-grouping.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
2+
3+
```esql
4+
FROM employees
5+
| WHERE still_hired
6+
| KEEP emp_no, languages, salary, hire_date
7+
| EVAL tenure = DATE_DIFF("year", hire_date, now())
8+
| DROP hire_date
9+
| INLINESTATS avg_salary = AVG(salary), count = count(*) BY languages, tenure
10+
```
11+
12+
| emp_no:integer | salary:integer | avg_salary:double | count:long | languages:integer | tenure:integer |
13+
| --- | --- | --- | --- | --- | --- |
14+
| 10001 | 57305 | 51130.5 | 2 | 2 | 39 |
15+
| 10002 | 56371 | 40180.0 | 3 | 5 | 39 |
16+
| 10004 | 36174 | 30749.0 | 2 | 5 | 38 |
17+
| 10005 | 63528 | 63528.0 | 1 | 1 | 36 |
18+
| 10007 | 74572 | 58644.0 | 2 | 4 | 36 |

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

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
```yaml {applies_to}
2+
serverless: preview
3+
stack: preview 9.2.0
4+
```
5+
6+
The `INLINE STATS` processing command groups rows according to a common value
7+
and calculates one or more aggregated values over the grouped rows. The results
8+
are appended as new columns to the input rows.
9+
10+
The command is identical to [`STATS`](/reference/query-languages/esql/commands/stats-by.md) except that it preserves all the columns from the input table.
11+
12+
**Syntax**
13+
14+
```esql
15+
INLINE STATS [column1 =] expression1 [WHERE boolean_expression1][,
16+
...,
17+
[columnN =] expressionN [WHERE boolean_expressionN]]
18+
[BY [grouping_name1 =] grouping_expression1[,
19+
...,
20+
[grouping_nameN = ] grouping_expressionN]]
21+
```
22+
23+
**Parameters**
24+
25+
`columnX`
26+
: The name by which the aggregated value is returned. If omitted, the name is
27+
equal to the corresponding expression (`expressionX`).
28+
If multiple columns have the same name, all but the rightmost column with this
29+
name will be ignored.
30+
31+
`expressionX`
32+
: An expression that computes an aggregated value.
33+
34+
`grouping_expressionX`
35+
: An expression that outputs the values to group by.
36+
If its name coincides with one of the existing or computed columns, that column will be overridden by this one.
37+
38+
`boolean_expressionX`
39+
: The condition that determines which rows are included when evaluating `expressionX`.
40+
41+
::::{note}
42+
Individual `null` values are skipped when computing aggregations.
43+
::::
44+
45+
46+
**Description**
47+
48+
The `INLINE STATS` processing command groups rows according to a common value
49+
(also known as the grouping key), specified after `BY`, and calculates one or more
50+
aggregated values over the grouped rows. The output table contains the same
51+
number of rows as the input table. The command only adds new columns or overrides
52+
existing columns with the same name as the result.
53+
54+
If column names overlap, existing column values may be overridden and column order
55+
may change. The new columns are added/moved so that they appear in the order
56+
they are defined in the `INLINE STATS` command.
57+
58+
For the calculation of each aggregated value, the rows in a group can be filtered with
59+
`WHERE`. If `BY` is omitted the aggregations are applied over the entire dataset.
60+
61+
The following [aggregation functions](/reference/query-languages/esql/functions-operators/aggregation-functions.md) are supported:
62+
63+
:::{include} ../../lists/aggregation-functions.md
64+
:::
65+
66+
The following [grouping functions](/reference/query-languages/esql/functions-operators/grouping-functions.md) are supported:
67+
68+
* [`BUCKET`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-bucket)
69+
* [`TBUCKET`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-tbucket)
70+
71+
72+
**Examples**
73+
74+
The following example shows how to calculate a statistic on one column and group
75+
by the values of another column.
76+
77+
:::{note}
78+
The `languages` column moves to the last position in the output table because it is
79+
a column overriden by the `INLINE STATS` command (it's the grouping key) and it is the last column defined by it.
80+
:::
81+
82+
:::{include} ../examples/inlinestats.csv-spec/max-salary.md
83+
:::
84+
85+
The following example shows how to calculate an aggregation over the entire dataset
86+
by omitting `BY`. The order of the existing columns is preserved and a new column
87+
with the calculated maximum salary value is added as the last column:
88+
89+
:::{include} ../examples/inlinestats.csv-spec/max-salary-without-by.md
90+
:::
91+
92+
The following example shows how to calculate multiple aggregations with multiple grouping keys:
93+
94+
:::{include} ../examples/inlinestats.csv-spec/multi-agg-multi-grouping.md
95+
:::
96+
97+
The following example shows how to filter which rows are used for each aggregation, using the `WHERE` clause:
98+
99+
:::{include} ../examples/inlinestats.csv-spec/avg-salaries-where.md
100+
:::
101+
102+
103+
**Limitations**
104+
105+
- The [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not currently supported.
106+
- `INLINE STATS` cannot yet have an unbounded [`SORT`](/reference/query-languages/esql/commands/sort.md) before it.
107+
You must either move the SORT after it, or add a [`LIMIT`](/reference/query-languages/esql/commands/limit.md) before the [`SORT`](/reference/query-languages/esql/commands/sort.md).

‎docs/reference/query-languages/esql/_snippets/lists/processing-commands.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
* [`KEEP`](/reference/query-languages/esql/commands/keep.md)
1010
* [`LIMIT`](/reference/query-languages/esql/commands/limit.md)
1111
* [`LOOKUP JOIN`](/reference/query-languages/esql/commands/lookup-join.md)
12+
* [preview] [`INLINE STATS`](/reference/query-languages/esql/commands/inlinestats-by.md)
1213
* [preview] [`MV_EXPAND`](/reference/query-languages/esql/commands/mv_expand.md)
1314
* [`RENAME`](/reference/query-languages/esql/commands/rename.md)
1415
* [preview] [`RERANK`](/reference/query-languages/esql/commands/rerank.md)

‎docs/reference/query-languages/esql/commands/inlinestats-by.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
navigation_title: "INLINE STATS"
3+
mapped_pages:
4+
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-commands.html#esql-inlinestats-by
5+
---
6+
7+
# `INLINE STATS` [esql-inlinestats-by]
8+
9+
:::{include} ../_snippets/commands/layout/inlinestats-by.md
10+
:::

‎docs/reference/query-languages/esql/commands/inlinestats.disabled‎

Lines changed: 0 additions & 102 deletions
This file was deleted.

‎docs/reference/query-languages/esql/functions-operators/aggregation-functions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ mapped_pages:
77
# {{esql}} aggregation functions [esql-aggregation-functions]
88

99

10-
The [`STATS`](/reference/query-languages/esql/commands/stats-by.md) command supports these aggregate functions:
10+
The [`STATS`](/reference/query-languages/esql/commands/stats-by.md) and [`INLINE STATS`](/reference/query-languages/esql/commands/inlinestats-by.md) commands support these aggregate functions:
1111

1212
:::{include} ../_snippets/lists/aggregation-functions.md
1313
:::

‎docs/reference/query-languages/esql/functions-operators/grouping-functions.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,19 @@ The [`STATS`](/reference/query-languages/esql/commands/stats-by.md) command supp
1212
:::{include} ../_snippets/lists/grouping-functions.md
1313
:::
1414

15+
The [`INLINE STATS`](/reference/query-languages/esql/commands/inlinestats-by.md) command supports these grouping functions:
16+
17+
* [`BUCKET`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-bucket)
18+
* [`TBUCKET`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-tbucket)
19+
1520

1621
:::{include} ../_snippets/functions/layout/bucket.md
1722
:::
1823

1924
:::{include} ../_snippets/functions/layout/tbucket.md
2025
:::
2126

27+
2228
:::{note}
2329
The `CATEGORIZE` function requires a [platinum license](https://www.elastic.co/subscriptions).
2430
:::

0 commit comments

Comments
 (0)