Skip to content

Document ES|QL SORT by expression #143705

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
wchaparro merged 5 commits into from
Mar 6, 2026
Merged

Document ES|QL SORT by expression #143705

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
200a4d6
Document ES|QL SORT by expression
wchaparro Mar 5, 2026
b7419a6
Merge branch 'main' into docs/esql-sort-by-expression-115011
wchaparro Mar 5, 2026
34ed00b
Update docs/reference/query-languages/esql/_snippets/commands/layout/…
wchaparro Mar 6, 2026
f2a2deb
Use DATE_EXTRACT for year in SORT expression examples
wchaparro Mar 6, 2026
a03015a
Merge branch 'main' into docs/esql-sort-by-expression-115011
wchaparro Mar 6, 2026
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
28 changes: 22 additions & 6 deletions docs/reference/query-languages/esql/_snippets/commands/layout/sort.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,26 @@ serverless: ga
stack: ga
```

The `SORT` processing command sorts a table on one or more columns.
The `SORT` processing command sorts a table on one or more expressions.

## Syntax

```esql
SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]]
SORT expression1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., expressionN [ASC/DESC][NULLS FIRST/NULLS LAST]]
```

## Parameters

`columnX`
: The column to sort on.
`expressionX`
: The expression to sort on. Can be a column name, a
[function](/reference/query-languages/esql/esql-functions-operators.md#esql-functions) (for example,
`length(field)`, `DATE_EXTRACT("year", date)`), or an arithmetic expression (for example, `salary * 2`).
The expression is evaluated per row and the result is used for ordering.
Comment on lines +18 to +20
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

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

year(date) is not an ES|QL function in this docs set (existing docs use DATE_EXTRACT("year", date) for year extraction). Using year(date) here will mislead readers and makes the example inconsistent with the function reference—please replace it with a valid ES|QL date function call (e.g., DATE_EXTRACT("year", date)).

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member Author

@wchaparro wchaparro Mar 6, 2026

Choose a reason for hiding this comment

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

good catch. updated


## Description

The `SORT` processing command sorts a table on one or more columns.
The `SORT` processing command sorts a table on one or more expressions. You can sort by any
expression, not only column names—for example, `length(first_name)` or `DATE_EXTRACT("year", hire_date)`.

The default sort order is ascending. Use `ASC` or `DESC` to specify an explicit
sort order.
Expand All @@ -36,7 +40,7 @@ sort order, `null` values are sorted first. You can change that by providing

## Examples

The following examples show how to control sort order, tie-breaking, and null placement.
The following examples show how to control sort order, tie-breaking, null placement, and sorting by expressions.

### Sort in default ascending order

Expand All @@ -57,3 +61,15 @@ The following examples show how to control sort order, tie-breaking, and null pl

:::{include} ../examples/docs.csv-spec/sortNullsFirst.md
:::

### Sort by expression

You can sort by any expression, not just column names. The following example sorts rows by the
length of the `first_name` field in descending order:

```esql
FROM employees
| KEEP first_name, last_name
| SORT length(first_name) DESC
| LIMIT 5
```
2 changes: 1 addition & 1 deletion docs/reference/query-languages/esql/limitations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Querying a column with an unsupported type returns an error. If a column with an

Some [field types](/reference/elasticsearch/mapping-reference/field-data-types.md) are not supported in all contexts:

* Spatial types are not supported in the [SORT](/reference/query-languages/esql/commands/sort.md) processing command. Specifying a column of one of these types as a sort parameter will result in an error:
* Spatial types are not supported in the [SORT](/reference/query-languages/esql/commands/sort.md) processing command. Specifying an expression that evaluates to one of these types as a sort key will result in an error:

* `geo_point`
* `geo_shape`
Expand Down
Loading