docs

Author: jan-elastic

docs/reference/esql/esql-commands.asciidoc

@@ -46,6 +46,7 @@ endif::[]
 * experimental:[] <<esql-lookup-join>>
 * experimental:[] <<esql-mv_expand>>
 * <<esql-rename>>
+* experimental:[] <<esql-sample>>
 * <<esql-sort>>
 * <<esql-stats-by>>
 * <<esql-where>>
@@ -70,6 +71,7 @@ include::processing-commands/limit.asciidoc[]
 include::processing-commands/lookup.asciidoc[]
 include::processing-commands/mv_expand.asciidoc[]
 include::processing-commands/rename.asciidoc[]
+include::processing-commands/sample.asciidoc[]
 include::processing-commands/sort.asciidoc[]
 include::processing-commands/stats.asciidoc[]
 include::processing-commands/where.asciidoc[]

docs/reference/esql/processing-commands/sample.asciidoc

@@ -0,0 +1,30 @@
+[discrete]
+[[esql-sample]]
+=== `SAMPLE`
+
+preview::[]
+
+The `SAMPLE` command samples a fraction of the table rows.
+
+**Syntax**
+
+[source,esql]
+----
+SAMPLE probability
+----
+
+*Parameters*
+
+`probability`::
+The probability that a row is included in the sample. The value must be between 0 and 1, exclusive.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/sample.csv-spec[tag=sampleForDocs]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/sample.csv-spec[tag=sampleForDocs-result]
+|===

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[]
+;