ES|QL sample documentation

Author: jan-elastic

docs/reference/query-languages/esql/_snippets/commands/examples/sample.csv-spec/sampleForDocs.md

@@ -0,0 +1,14 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+```esql
+FROM employees
+| KEEP emp_no
+| SAMPLE 0.05
+```
+
+| emp_no:integer |
+| --- |
+| 10018 |
+| 10024 |
+| 10062 |
+| 10081 |

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

@@ -0,0 +1,26 @@
+## `SAMPLE` [esql-sample]
+
+::::{warning}
+This functionality is in technical preview and may be
+changed or removed in a future release. Elastic will work to fix any
+issues, but features in technical preview are not subject to the support
+SLA of official GA features.
+::::
+
+The `SAMPLE` command samples a fraction of the table rows.
+
+**Syntax**
+
+```esql
+SAMPLE probability
+```
+
+**Parameters**
+
+`probability`
+:   The probability that a row is included in the sample. The value must be between 0 and 1, exclusive.
+
+**Examples**
+
+:::{include} ../examples/sample.csv-spec/sampleForDocs.md
+:::

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

@@ -9,6 +9,7 @@
 * [preview] [`LOOKUP JOIN`](../../commands/processing-commands.md#esql-lookup-join)
 * [preview] [`MV_EXPAND`](../../commands/processing-commands.md#esql-mv_expand)
 * [`RENAME`](../../commands/processing-commands.md#esql-rename)
+* [preview] [`SAMPLE`](../../commands/processing-commands.md#esql-sample)
 * [`SORT`](../../commands/processing-commands.md#esql-sort)
 * [`STATS`](../../commands/processing-commands.md#esql-stats-by)
 * [`WHERE`](../../commands/processing-commands.md#esql-where)

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

@@ -50,6 +50,9 @@ mapped_pages:
 :::{include} ../_snippets/commands/layout/rename.md
 :::
 
+:::{include} ../_snippets/commands/layout/sample.md
+:::
+
 :::{include} ../_snippets/commands/layout/sort.md
 :::
 

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

@@ -221,3 +221,28 @@ FROM employees
 is_expected:boolean
 true
 ;
+
+
+example for docs
+required_capability: sample_v3
+
+// tag::sampleForDocs[]
+FROM employees
+| KEEP emp_no
+| SAMPLE 0.05
+// end::sampleForDocs[]
+// Hardcode the sample values to work around the limitations of the CSV tests in the 
+// presence of randomness, and be able to specify an expected result for the docs.
+| STATS emp_no = COUNT()
+| EVAL emp_no = [10018, 10024, 10062, 10081]
+| MV_EXPAND emp_no
+;
+
+// tag::sampleForDocs-result[]
+emp_no:integer
+10018
+10024
+10062
+10081
+// end::sampleForDocs-result[]
+;