ES|QL: Add docs for FORK

docs/reference/query-languages/esql/_snippets/commands/examples/fork.csv-spec/simpleFork.md

@@ -0,0 +1,14 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+```esql
+FROM employees
+| FORK ( WHERE emp_no == 10001 )
+       ( WHERE emp_no == 10002 )
+| KEEP emp_no, _fork
+| SORT emp_no
+```
+
+| emp_no:integer | _fork:keyword |
+| --- | --- |
+| 10001 | fork1 |
+| 10002 | fork2 |

docs/reference/query-languages/esql/_snippets/commands/examples/fork.csv-spec/simpleForkWithStats.md

@@ -0,0 +1,19 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+```esql
+FROM books METADATA _score
+| WHERE author:"Faulkner"
+| EVAL score = round(_score, 2)
+| FORK (SORT score DESC, author | LIMIT 5 | KEEP author, score)
+       (STATS total = COUNT(*))
+| SORT _fork, score DESC, author
+```
+
+| author:text | score:double | _fork:keyword | total:long |
+| --- | --- | --- | --- |
+| William Faulkner | 2.39 | fork1 | null |
+| William Faulkner | 2.39 | fork1 | null |
+| Colleen Faulkner | 1.59 | fork1 | null |
+| Danny Faulkner | 1.59 | fork1 | null |
+| Keith Faulkner | 1.59 | fork1 | null |
+| null | null | fork2 | 18 |

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

@@ -0,0 +1,67 @@
+## `FORK` [esql-fork]
+
+```yaml {applies_to}
+serverless: preview
+stack: preview 9.1.0
+```
+
+The `FORK` processing command runs multiple execution branches and outputs the
+results back into a single table.
+
+**Syntax**
+
+```esql
+FORK ( <processing_commands> ) ( <processing_commands> ) ... ( <processing_commands> )
+```
+
+**Description**
+
+The `FORK` processing command feeds the input rows into multiple execution
+branches and outputs the results into a single table, enhanced with a
+discriminator column called `_fork`.
+
+The values of the discriminator column `_fork` are `fork1`, `fork2`, ... and
+they designate which `FORK` branch the current row is coming from.
+The values of the `_fork` column always start with `fork1`, which indicates that
+the row is coming from the first branch.
+
+The `FORK` branches can output different columns as long as there exists no
+column with the same name and different data types in two different `FORK`
+branches.
+
+When a column does not exist in a `FORK` branch, but it exists in the output of
+other branches, `FORK` will add `null` values to the rows that have missing
+columns.
+
+`FORK` preserves the order of the rows from each subset, but it does not
+guarantee that the rows will follow the same order in which the `FORK` branches
+are defined. The rows from the first branch can be interleaved with the rows
+from subsequent branches. Use `SORT _fork` after `FORK` if you need to change
+this behaviour.
+
+`FORK` branches receive an implicit `LIMIT 1000` if no `LIMIT` is provided.
+
+::::{note}
+`FORK` supports at most 8 execution branches.
+::::
+
+::::{note}
+Using remote cluster references and `FORK` is not supported.
+::::
+
+::::{note}
+Using more than one `FORK` command in a query is not supported.
+::::
+
+**Examples**
+
+In the following example, each `FORK` branch returns one row.
+Notice how `FORK` adds a `_fork` that indicates from which row the branch is
+coming:
+
+:::{include} ../examples/fork.csv-spec/simpleFork.md
+
+The next example, returns total number of rows that match the query along with
+the top five rows sorted by score.
+
+:::{include} ../examples/fork.csv-spec/simpleForkWithStats.md

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

@@ -4,6 +4,7 @@
 * [`ENRICH`](../../commands/processing-commands.md#esql-enrich)
 * [`EVAL`](../../commands/processing-commands.md#esql-eval)
 * [`GROK`](../../commands/processing-commands.md#esql-grok)
+* [preview] [`FORK`](...)
 * [`KEEP`](../../commands/processing-commands.md#esql-keep)
 * [`LIMIT`](../../commands/processing-commands.md#esql-limit)
 * [`LOOKUP JOIN`](../../commands/processing-commands.md#esql-lookup-join)

docs/reference/query-languages/esql/commands/processing-commands.md

@@ -32,6 +32,9 @@ mapped_pages:
 :::{include} ../_snippets/commands/layout/eval.md
 :::
 
+:::{include} ../_snippets/commands/layout/fork.md
+:::
+
 :::{include} ../_snippets/commands/layout/grok.md
 :::
 

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

@@ -5,16 +5,44 @@
 simpleFork
 required_capability: fork_v9
 
+// tag::simpleFork[]
 FROM employees
 | FORK ( WHERE emp_no == 10001 )
        ( WHERE emp_no == 10002 )
 | KEEP emp_no, _fork
 | SORT emp_no
+// end::simpleFork[]
 ;
 
+// tag::simpleFork-result-[]
 emp_no:integer | _fork:keyword
 10001          | fork1
 10002          | fork2
+// end::simpleFork-result[]
+;
+
+simpleForkWithStats
+required_capability: fork_v9
+
+// tag::simpleForkWithStats[]
+FROM books METADATA _score
+| WHERE author:"Faulkner"
+| EVAL score = round(_score, 2)
+| FORK (SORT score DESC, author | LIMIT 5 | KEEP author, score)
+       (STATS total = COUNT(*))
+| SORT _fork, score DESC, author
+// end::simpleForkWithStats[]
+;
+
+// tag::simpleForkWithStats-result[]
+author:text      | score:double | _fork:keyword | total:long
+William Faulkner | 2.39         | fork1         | null
+William Faulkner | 2.39         | fork1         | null
+Colleen Faulkner | 1.59         | fork1         | null
+Danny Faulkner   | 1.59         | fork1         | null
+Keith Faulkner   | 1.59         | fork1         | null
+null             | null         | fork2         | 18
+// end::simpleForkWithStats-result[]
 ;
 
 forkWithWhereSortAndLimit