ESQL: INLINESTATS docs by astefan · Pull Request #134480 · elastic/elasticsearch

astefan · 2025-09-10T17:10:07Z

Fixes #124718

elasticsearchmachine · 2025-09-10T18:24:27Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2025-09-10T18:24:27Z

Pinging @elastic/core-docs (Team:Docs)

github-actions · 2025-09-11T07:19:52Z

🔍 Preview links for changed docs

github-actions · 2025-09-11T07:19:53Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

bpintea

Thanks Andrei for taking on the docs!

bpintea · 2025-09-11T13:00:27Z

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

+The command is identical to [`STATS`](/reference/query-languages/esql/commands/stats-by.md) except that it does not reduce
+the number of columns in the output table.


Alternative / optional:

Suggested change

The command is identical to [`STATS`](/reference/query-languages/esql/commands/stats-by.md) except that it does not reduce

the number of columns in the output table.

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.

bpintea · 2025-09-11T13:07:33Z

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

+INLINE STATS [column1 =] expression1 [WHERE boolean_expression1][,
+      ...,
+      [columnN =] expressionN [WHERE boolean_expressionN]]
+      [BY grouping_expression1[, ..., grouping_expressionN]]


This is inherited, but [BY grouping_expression1[, ..., grouping_expressionN]] isn't as "detailed" as it could/should be:

[BY [grouping_name1 =] grouping_expression1[, ..., [grouping_nameN = ] grouping_expressionN]]

This is relevant below [§].

Indeed, you are right. I've changed it.

bpintea · 2025-09-11T13:11:03Z

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

+
+`grouping_expressionX`
+:   An expression that outputs the values to group by.
+    If its name coincides with one of the computed columns, that column will be ignored.


[§] In this case, the "name collision" might not be clear, since, as given, that's en expression.

Also, for INLINE STATS we have the non-computed columns.

Suggested change

If its name coincides with one of the computed columns, that column will be ignored.

If its name coincides with one of the existing or computed columns, that column will be overridden by this one.

Another option: If the name matches an existing or computed column, this new column will replace it.

Thank you both. I've used @bpintea's suggestion.

bpintea · 2025-09-11T13:19:52Z

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

+:::{include} ../examples/inlinestats.csv-spec/avg-salaries-where.md
+:::
+
+Specifying the output column name is optional. If not specified, the new column


Optional: I'd drop this line. It's specified already in the synopsis and unlike for STATS, we don't add an example here.

bpintea · 2025-09-11T13:20:21Z

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

+
+**Limitations**
+
+- [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not


Suggested change

- [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not

- The [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not

bpintea · 2025-09-11T13:21:28Z

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



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


Suggested change

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

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:

leemthompo

Looks good, few (mainly language clarification) suggestions and couple questions from me :)

leemthompo · 2025-09-11T14:34:57Z

docs/redirects.yml

+      - to: 'reference/query-languages/esql/commands/inlinestats-by.md'
+        anchors: {'esql-inlinestats-by'}


Don't think you need this redirect, this was only required when we broke out the commands into standalone sub-pages, but this is a brand new page

leemthompo · 2025-09-11T14:37:06Z

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

+
+`grouping_expressionX`
+:   An expression that outputs the values to group by.
+    If its name coincides with one of the computed columns, that column will be ignored.


Another option: If the name matches an existing or computed column, this new column will replace it.

leemthompo · 2025-09-11T14:38:02Z

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

+    If its name coincides with one of the computed columns, that column will be ignored.
+
+`boolean_expressionX`
+:   The condition that must be met for a row to be included in the evaluation of `expressionX`.


Suggested change

: The condition that must be met for a row to be included in the evaluation of `expressionX`.

: The condition that determines which rows are included when evaluating `expressionX`.

leemthompo · 2025-09-11T15:20:47Z

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

+The `INLINE STATS` processing command groups rows according to a common value
+(what comes after `BY`) and calculates one or more aggregated values over the
+grouped rows. The output table contains the same number of rows as the input
+table and the command just adds new columns or overrides any existent ones with
+the same name to the result. The resulting calculated values are matched to the
+input rows according to the common value(s) (also known as grouping key(s)).


Suggested change

The `INLINE STATS` processing command groups rows according to a common value

(what comes after `BY`) and calculates one or more aggregated values over the

grouped rows. The output table contains the same number of rows as the input

table and the command just adds new columns or overrides any existent ones with

the same name to the result. The resulting calculated values are matched to the

input rows according to the common value(s) (also known as grouping key(s)).

The `INLINE STATS` processing command groups rows according to a common value

(also known as the grouping key), specified after `BY`, and calculates one or more

aggregated values over the grouped rows. The output table contains the same

number of rows as the input table. The command only adds new columns or overrides existing columns with the same name as the result.

suggestion for concision

leemthompo · 2025-09-11T15:41:37Z

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

+In case there are overlapping column names between the newly added columns and the
+existing ones, besides overriding the existing columns, there can be a change in
+the column order. The new columns are added/moved so that they appear in the order
+they are defined in the `INLINE STATS` command.


Suggested change

In case there are overlapping column names between the newly added columns and the

existing ones, besides overriding the existing columns, there can be a change in

the column order. The new columns are added/moved so that they appear in the order

they are defined in the `INLINE STATS` command.

When using a `BY` clause, columns are reordered to match the structure of the

`INLINE STATS` command - calculated columns appear first, followed by grouping

columns.

I might (probably) have misunderstood, but are naming collisions + overrides separate to column reordering? If so my suggestion tries to clarify that, otherwise, just ignore :)

In my mind, the original wording explains inline stats behavior better. But there is a small change I need to make to the original text still.

besides overriding the existing columns, there can be

to

besides overriding the existing columns values, there can be

I'd simplify the first sentence anyway for readability, maybe something like:

- In case there are overlapping column names between the newly added columns and the existing ones, besides overriding the existing columns, there can be a change in the column order. + If column names overlap, existing column values may be overridden and column order may change.

Yep, much better. Changed.

leemthompo · 2025-09-11T15:54:58Z

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

+Calculating a statistic and grouping by the values of another column; note also
+that `languages` column is moved as the last column in the output since it is
+used as grouping key (the `KEEP` command before `INLINE STATS` had `languages`
+set as the second column):


Suggested change

Calculating a statistic and grouping by the values of another column; note also

that `languages` column is moved as the last column in the output since it is

used as grouping key (the `KEEP` command before `INLINE STATS` had `languages`

set as the second column):

The following example shows how to calculate a statistic on one column and group

by the values of another column.

:::{note}

The `languages` column moves to the last position in the output table because it is

the grouping key.

:::

attempt to make the language flow clearer, take what you need if feel it isn't quite accurate!

leemthompo · 2025-09-11T15:56:44Z

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

+Omitting `BY` calculates the aggregation applied over the entire dataset, the
+order of the existent columns is preserved and a new column with the calculated
+maximum salary value is added as the last column:


Suggested change

Omitting `BY` calculates the aggregation applied over the entire dataset, the

order of the existent columns is preserved and a new column with the calculated

maximum salary value is added as the last column:

The following example shows how to calculate an aggregation over the entire dataset

by omitting `BY`. The order of the existing columns is preserved and a new column

with the calculated maximum salary value is added as the last column:

leemthompo · 2025-09-11T15:57:45Z

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

+:::{include} ../examples/inlinestats.csv-spec/max-salary-without-by.md
+:::
+
+It’s possible to calculate multiple values in more complex queries:


Suggested change

It’s possible to calculate multiple values in more complex queries:

The following example shows how to calculate multiple aggregations with multiple grouping keys:

leemthompo · 2025-09-11T16:01:26Z

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

+:::{include} ../examples/inlinestats.csv-spec/multi-agg-multi-grouping.md
+:::
+
+To filter the rows that go into an aggregation, use the `WHERE` clause:


Suggested change

To filter the rows that go into an aggregation, use the `WHERE` clause:

The following example shows how to filter which rows are used for each aggregation, using the `WHERE` clause:

leemthompo · 2025-09-11T16:02:53Z

docs/reference/query-languages/esql/limitations.md

 {{esql}} only supports the UTC timezone.


+## INLINE STATS limitations [esql-limitations-inlinestats]


Do we need to duplicate limitations here? No strong opinions from me.

I have a preference for doing it like this, having some experience with users interaction for ES EQL and ES SQL projects where a separate Limitations page helped Support reason much better about some specific things not being available in those projects.

But, if there are other principles behind documentation for ES|QL, I can definitely follow them. Just le me know.

fair enough 👍

bpintea · 2025-09-11T16:56:57Z

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

+and calculates one or more aggregated values over the grouped rows. The results
+are appended as new columns to the input rows.
+
+The command is identical to [`STATS`](/reference/query-languages/esql/commands/stats-by.md) except that it does not reduce


Should we mention (somewhere) that the STATS will break down MVs fields it groups by, by individual SVs, while INLINE STATS links back to the MV field?
I'm referring to the behaviour noted in this test (which, IMO is correct, answering to the question there).
Though maybe that's intuitive.

Good point. I left this with no MV specification because I regarded that test result something to discuss further.

I added a mention in the csv-spec file about docs update when/if we decide on the MV behavior.

…search into inlinestats_docs

…inlinestats_docs

leemthompo

LGTM. Thanks @astefan!

Fixes elastic#124718

docs

71b688f

astefan added >docs General docs changes :Analytics/ES|QL AKA ESQL v9.2.0 labels Sep 10, 2025

astefan marked this pull request as ready for review September 10, 2025 18:24

astefan requested a review from bpintea September 10, 2025 18:24

elasticsearchmachine added Team:Docs Meta label for docs team Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) labels Sep 10, 2025

astefan requested a review from leemthompo September 10, 2025 19:40

astefan added 4 commits September 11, 2025 09:40

update

a217074

More

08d4748

Even more

11ee344

...

be9680e

astefan and others added 2 commits September 11, 2025 10:32

...

e036dcf

Merge branch 'main' into inlinestats_docs

3bc3f8a

bpintea approved these changes Sep 11, 2025

View reviewed changes

leemthompo reviewed Sep 11, 2025

View reviewed changes

bpintea reviewed Sep 11, 2025

View reviewed changes

astefan added 3 commits September 12, 2025 15:29

Address reviews

a97e395

Merge branch 'inlinestats_docs' of https://github.com/astefan/elastic…

d9fa29f

…search into inlinestats_docs

Merge branch 'main' of https://github.com/elastic/elasticsearch into …

e82a8f7

…inlinestats_docs

astefan requested a review from leemthompo September 12, 2025 12:30

Address one more review and fix a surprisingly wrong test

31ee97a

leemthompo approved these changes Sep 12, 2025

View reviewed changes

astefan added the auto-merge-without-approval Automatically merge pull request when CI checks pass (NB doesn't wait for reviews!) label Sep 12, 2025

Update docs test

52e32db

elasticsearchmachine merged commit f969349 into elastic:main Sep 12, 2025
34 checks passed

astefan deleted the inlinestats_docs branch September 12, 2025 14:19

gmjehovich pushed a commit to gmjehovich/elasticsearch that referenced this pull request Sep 18, 2025

ESQL: INLINESTATS docs (elastic#134480)

3c0ac2b

Fixes elastic#124718

		The command is identical to [`STATS`](/reference/query-languages/esql/commands/stats-by.md) except that it does not reduce
		the number of columns in the output table.

	If its name coincides with one of the computed columns, that column will be ignored.
	If its name coincides with one of the existing or computed columns, that column will be overridden by this one.


		Limitations

		- [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not

	- [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not
	- The [`CATEGORIZE`](/reference/query-languages/esql/functions-operators/grouping-functions.md#esql-categorize) grouping function is not



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

		- to: 'reference/query-languages/esql/commands/inlinestats-by.md'
		anchors: {'esql-inlinestats-by'}

	: The condition that must be met for a row to be included in the evaluation of `expressionX`.
	: The condition that determines which rows are included when evaluating `expressionX`.

-Calculating a statistic and grouping by the values of another column; note also
-that `languages` column is moved as the last column in the output since it is
-used as grouping key (the `KEEP` command before `INLINE STATS` had `languages`
-set as the second column):
+The following example shows how to calculate a statistic on one column and group
+by the values of another column.
+:::{note}
+The `languages` column moves to the last position in the output table because it is
+the grouping key.
+:::

	It’s possible to calculate multiple values in more complex queries:
	The following example shows how to calculate multiple aggregations with multiple grouping keys:

	To filter the rows that go into an aggregation, use the `WHERE` clause:
	The following example shows how to filter which rows are used for each aggregation, using the `WHERE` clause:

		{{esql}} only supports the UTC timezone.


		## INLINE STATS limitations [esql-limitations-inlinestats]

Conversation

astefan commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticsearchmachine commented Sep 10, 2025

Uh oh!

elasticsearchmachine commented Sep 10, 2025

Uh oh!

github-actions bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Sep 11, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

bpintea left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

astefan Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

astefan commented Sep 10, 2025 •

edited

Loading

github-actions bot commented Sep 11, 2025 •

edited

Loading

leemthompo Sep 11, 2025 •

edited

Loading

astefan Sep 12, 2025 •

edited

Loading