From df76c15edd71de8df14a42baf4cc4a1c396e8d77 Mon Sep 17 00:00:00 2001
From: Jan Kuipers <148754765+jan-elastic@users.noreply.github.com>
Date: Tue, 17 Jun 2025 10:56:14 +0200
Subject: [PATCH] ES|QL sample documentation (#129350)

* ES|QL sample documentation

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

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

---------

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
---
 .../examples/sample.csv-spec/sampleForDocs.md | 14 +++++++++++
 .../esql/_snippets/commands/layout/sample.md  | 23 +++++++++++++++++
 .../_snippets/lists/processing-commands.md    |  1 +
 .../esql/commands/processing-commands.md      |  3 +++
 .../src/main/resources/sample.csv-spec        | 25 +++++++++++++++++++
 5 files changed, 66 insertions(+)
 create mode 100644 docs/reference/query-languages/esql/_snippets/commands/examples/sample.csv-spec/sampleForDocs.md
 create mode 100644 docs/reference/query-languages/esql/_snippets/commands/layout/sample.md

diff --git a/docs/reference/query-languages/esql/_snippets/commands/examples/sample.csv-spec/sampleForDocs.md b/docs/reference/query-languages/esql/_snippets/commands/examples/sample.csv-spec/sampleForDocs.md
new file mode 100644
index 000000000000..dd4c69491db4
--- /dev/null
+++ b/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 |
diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md b/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md
new file mode 100644
index 000000000000..8790b4a21d50
--- /dev/null
+++ b/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md
@@ -0,0 +1,23 @@
+## `SAMPLE` [esql-sample]
+
+```yaml {applies_to}
+stack: preview 9.1
+```
+
+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
+:::
diff --git a/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md b/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md
index fefb0dcc84b0..3ecd53d54095 100644
--- a/docs/reference/query-languages/esql/_snippets/lists/processing-commands.md
+++ b/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)
diff --git a/docs/reference/query-languages/esql/commands/processing-commands.md b/docs/reference/query-languages/esql/commands/processing-commands.md
index 22cacb507ddb..57084779d6d7 100644
--- a/docs/reference/query-languages/esql/commands/processing-commands.md
+++ b/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
 :::
 
diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/sample.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/sample.csv-spec
index 47bb70bd8ce2..8ecf1b7d374d 100644
--- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/sample.csv-spec
+++ b/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[]
+;