[ESQL] Makes LIMIT BY Tech Preview

docs/changelog/145225.yaml

@@ -0,0 +1,6 @@
+area: ES|QL
+issues:
+  - 112918
+pr: 145225
+summary: Adds LIMIT BY ESQL command in Tech Preview
+type: enhancement

docs/reference/query-languages/esql/_snippets/commands/examples/limit.csv-spec/limitBy.md

@@ -0,0 +1,14 @@
+% This is generated by ESQL's CommandDocsTests. Do not edit it. See ../README.md for how to regenerate it.
+
+```esql
+FROM employees
+| SORT salary DESC
+| LIMIT 1 BY gender
+| KEEP first_name, last_name, salary, gender
+```
+
+| first_name:keyword | last_name:keyword | salary:integer | gender:keyword |
+| --- | --- | --- | --- |
+| Otmar | Herbst | 74999 | M |
+| Tzvetan | Zielinski | 74572 | F |
+| Lillian | Haddadi | 73717 | null |

docs/reference/query-languages/esql/_snippets/commands/examples/limit.csv-spec/limitByMultipleGroups.md

@@ -0,0 +1,7 @@
+% This is generated by ESQL's CommandDocsTests. Do not edit it. See ../README.md for how to regenerate it.
+
+```esql
+FROM employees
+| SORT salary DESC
+| LIMIT 1 BY languages, gender
+```

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

@@ -7,23 +7,62 @@ The `LIMIT` processing command limits the number of rows returned.
 
 ## Syntax
 
+::::{applies-switch}
+
+:::{applies-item} { stack: ga, "serverless": "ga"}
 ```esql
 LIMIT max_number_of_rows
 ```
+:::
+
+:::{applies-item} { "stack": "preview 9.4+", "serverless": "preview" }
+```esql
+LIMIT max_number_of_rows [BY grouping_expr1[, ..., grouping_exprN]]
+```
+:::
+::::
 
 ## Parameters
 
 `max_number_of_rows`
-:   The maximum number of rows to return.
+:   The maximum number of rows to return. When `BY` is specified, the maximum
+number of rows to return **per group**.
+
+`grouping_exprX` {applies_to}`serverless: preview` {applies_to}`stack: preview 9.4+`
+:   An expression that outputs the values to group by.
 
 ## Description
 
 Use the `LIMIT` processing command to limit the number of rows returned.
 
+When `BY` is specified, up to `max_number_of_rows` rows are retained for each
+distinct combination of the grouping expressions.
+Precede `LIMIT <N> BY` with a `SORT` to keep the top N for each group.
+
 :::{include} ../../common/result-set-size-limitation.md
 :::
 
-## Example
+## Examples
+
+### Limit
 
 :::{include} ../examples/limit.csv-spec/basic.md
 :::
+
+### With groups
+```{applies_to}
+stack: preview 9.4
+serverless: preview
+```
+
+:::{include} ../examples/limit.csv-spec/limitBy.md
+:::
+
+### Group by multiple values
+```{applies_to}
+stack: preview 9.4
+serverless: preview
+```
+
+:::{include} ../examples/limit.csv-spec/limitByMultipleGroups.md
+:::

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

@@ -19,6 +19,56 @@ emp_no:integer
 // LIMIT BY
 //
 
+docsLimitBy
+required_capability: esql_limit_by
+
+// tag::limitBy[]
+FROM employees
+| SORT salary DESC
+| LIMIT 1 BY gender
+| KEEP first_name, last_name, salary, gender
+// end::limitBy[]
+;
+
+// tag::limitBy-result[]
+first_name:keyword | last_name:keyword | salary:integer | gender:keyword
+Otmar              | Herbst            | 74999          | M
+Tzvetan            | Zielinski         | 74572          | F
+Lillian            | Haddadi           | 73717          | null
+// end::limitBy-result[]
+;
+
+docsLimitByMultipleGroups
+required_capability: esql_limit_by
+
+// tag::limitByMultipleGroups[]
+FROM employees
+| SORT salary DESC
+| LIMIT 1 BY languages, gender
+// end::limitByMultipleGroups[]
+| SORT languages DESC NULLS LAST, gender DESC NULLS LAST, salary DESC
+| KEEP first_name, last_name, salary, languages, gender
+;
+
+first_name:keyword | last_name:keyword | salary:integer | languages:integer | gender:keyword
+Premal             | Baek              | 52833          | 5                 | M
+Arumugam           | Ossenbruggen      | 66817          | 5                 | F
+Patricio           | Bridgland         | 48942          | 5                 | null
+Mayumi             | Schueller         | 65367          | 4                 | M
+Tzvetan            | Zielinski         | 74572          | 4                 | F
+Duangkaew          | Piveteau          | 45797          | 4                 | null
+Moss               | Shanbhogue        | 74970          | 3                 | M
+Erez               | Ritzmann          | 62405          | 3                 | F
+Georgi             | Facello           | 57305          | 2                 | M
+Valter             | Sullins           | 73578          | 2                 | F
+Kazuhito           | Cappelletti       | 61358          | 2                 | null
+null               | Merlo             | 70011          | 1                 | M
+Sumant             | Peac              | 66174          | 1                 | F
+Lillian            | Haddadi           | 73717          | 1                 | null
+Otmar              | Herbst            | 74999          | null              | M
+Divier             | Reistad           | 73851          | null              | F
+;
+
 limitBy
 required_capability: esql_limit_by
 
@@ -354,6 +404,7 @@ Mayumi             | Schueller         | 65367          | 4                 | M
 
 sortLimitByQualifiedName
 required_capability: esql_topn_by
+required_capability: name_qualifiers
 
 FROM employees
 | SORT salary DESC

x-pack/plugin/esql/src/main/antlr/EsqlBaseParser.g4

@@ -226,7 +226,7 @@ limitCommand
     ;
 
 limitByGroupKey:
-    {this.isDevVersion()}? BY booleanExpression (COMMA booleanExpression)*
+    BY booleanExpression (COMMA booleanExpression)*
     ;
 
 sortCommand

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

@@ -2351,12 +2351,12 @@ public enum Cap {
          * Enables the feature LIMIT n BY expr1, expr2 for retaining at most n docs per group.
          * The feature will not work if we had SORT | LIMIT n BY
          */
-        ESQL_LIMIT_BY(Build.current().isSnapshot()),
+        ESQL_LIMIT_BY,
 
         /**
          * Enables the SORT | LIMIT n BY expr1, expr2 support, see ESQL_LIMIT_BY for more context
          */
-        ESQL_TOPN_BY(Build.current().isSnapshot()),
+        ESQL_TOPN_BY,
 
         /**
          * Corrects a bug with ENRICH when a shard does not contain an index field and we use LIMIT BY on top