Skip to content

ES|QL sample documentation #129350

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 17, 2025
+66 −0
Merged

ES|QL sample documentation #129350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c813a0
ES|QL sample documentation
jan-elastic Jun 12, 2025
e412b3f
Update docs/reference/query-languages/esql/_snippets/commands/layout/…
jan-elastic Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions ...ery-languages/esql/_snippets/commands/examples/sample.csv-spec/sampleForDocs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
23 changes: 23 additions & 0 deletions docs/reference/query-languages/esql/_snippets/commands/layout/sample.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## `SAMPLE` [esql-sample]

```yaml {applies_to}
stack: preview 9.1
Copy link
Contributor

@leemthompo leemthompo Jun 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alex-spies this is the correct way of marking versioning/lifecycle (preview/beta/GA) in the new docs

We haven't consolidated all the existing pages yet, (see #128576) but we should start using this on a go-forward basis

The docs build will render the preview pill and there will be more explicit tooltips soon too :)

Copy link
Contributor

@leemthompo leemthompo Jun 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's much nicer because we're using structured metadata that doesn't require as much manual maintenance, because the docs build handles the output

Say this goes GA in 9.3, all we have to do is append a comma-separated version and the docs will be up-to-date and version-aware on the page without having to switch versions using different URLs:

eg

stack: preview 9.1, ga 9.3

Copy link
Contributor

@alex-spies alex-spies Jun 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, this is great. Thanks for the explanation!

```
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
:::
1 change: 1 addition & 0 deletions docs/reference/query-languages/esql/_snippets/lists/processing-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
3 changes: 3 additions & 0 deletions docs/reference/query-languages/esql/commands/processing-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ mapped_pages:
:::{include} ../_snippets/commands/layout/rename.md
:::

:::{include} ../_snippets/commands/layout/sample.md
:::

:::{include} ../_snippets/commands/layout/sort.md
:::

Expand Down
25 changes: 25 additions & 0 deletions x-pack/plugin/esql/qa/testFixtures/src/main/resources/sample.csv-spec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +234 to +238
Copy link
Contributor

@alex-spies alex-spies Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Haha, this is beautiful. But I like that we're making sure the syntax is valid, even though the output is not related to the query that's in the docs!

Copy link
Contributor Author

@jan-elastic jan-elastic Jun 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I know. Within the system's current limitations, I don't see anything better than this...

;

// tag::sampleForDocs-result[]
emp_no:integer
10018
10024
10062
10081
// end::sampleForDocs-result[]
;
Loading