Document ES|QL SORT by expression

[wchaparro]

Summary

Documents that the ES|QL SORT command accepts any expression as a sort key, not only column names (feature added in 8.14.0, see #107158).

Changes

• SORT command (commands/sort.md via layout snippet): Updated intro, syntax, and parameters to use "expression" instead of "column"; clarified that sort keys can be column names, functions (e.g. length(field), year(date)), or arithmetic. Added a Sort by expression example subsection with SORT length(first_name) DESC.
• Limitations: Aligned SORT limitation wording with "expression" terminology.

Fixes #115011

Made with Cursor

[elasticsearchmachine]

Pinging @elastic/es-analytical-engine (Team:Analytics)

[github-actions]

🔍 Preview links for changed docs

• docs/reference/query-languages/esql/limitations.md

[github-actions]

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

• Check out the cumulative docs guidelines
• Reach out in the #docs Slack channel

[ivancea]

LGTM!

[Copilot]

Pull request overview

Updates the ES|QL documentation to reflect that SORT supports sorting by arbitrary expressions (not just column names), aligning docs with the feature introduced in 8.14.0.

Changes:

• Update SORT command intro/syntax/parameter wording from “column” to “expression”, and add an example showing sorting by an expression.
• Adjust ES|QL limitations wording to match the updated SORT “expression” terminology.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/reference/query-languages/esql/limitations.md	Updates SORT limitation wording to refer to expressions evaluating to spatial types.
docs/reference/query-languages/esql/_snippets/commands/layout/sort.md	Documents expression-based sorting, updates syntax/parameter docs, and adds a “Sort by expression” example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

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)).

[wchaparro]

good catch. updated

[Copilot]

The description example uses year(hire_date), but there doesn't appear to be an ES|QL year() function in the docs (year extraction is documented via DATE_EXTRACT("year", <date>)). Please update this example to a valid ES|QL function to avoid confusing users.