From 1c813a0156e876f10618596ca575c2f09bd9cd6b Mon Sep 17 00:00:00 2001 From: Jan Kuipers Date: Thu, 12 Jun 2025 17:01:12 +0200 Subject: [PATCH 1/2] ES|QL sample documentation --- .../examples/sample.csv-spec/sampleForDocs.md | 14 ++++++++++ .../esql/_snippets/commands/layout/sample.md | 26 +++++++++++++++++++ .../_snippets/lists/processing-commands.md | 1 + .../esql/commands/processing-commands.md | 3 +++ .../src/main/resources/sample.csv-spec | 25 ++++++++++++++++++ 5 files changed, 69 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 0000000000000..dd4c69491db4a --- /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 0000000000000..a1d6cfc747f90 --- /dev/null +++ b/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 +::: 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 fefb0dcc84b0c..3ecd53d540955 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 22cacb507ddbc..57084779d6d7a 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 47bb70bd8ce26..8ecf1b7d374de 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[] +; From e412b3fbbcfd6f014d29e11636530c0f1f0f4e87 Mon Sep 17 00:00:00 2001 From: Jan Kuipers <148754765+jan-elastic@users.noreply.github.com> Date: Fri, 13 Jun 2025 11:29:49 +0200 Subject: [PATCH 2/2] Update docs/reference/query-languages/esql/_snippets/commands/layout/sample.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- .../esql/_snippets/commands/layout/sample.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md b/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md index a1d6cfc747f90..8790b4a21d50a 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/sample.md @@ -1,11 +1,8 @@ ## `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. -:::: +```yaml {applies_to} +stack: preview 9.1 +``` The `SAMPLE` command samples a fraction of the table rows.