Add ESQL CPS doc by leemthompo · Pull Request #5402 · elastic/docs-content

leemthompo · 2026-03-09T08:35:42Z

Issue: #4167

Duplication

If ESQL deserves its own page for CPS, then a minimum of reiteration is required.

That said, I'm sure there's some duplication versus the core CPS docs here that might be overkill, reviewer please flag what you think doesn't need to be reiterated here.

Important

Eventually this doc will live in elasticsearch alongside the bulk of the rest of the ESQL docs, so this PR will get closed and recreated

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

Tool(s) and model(s) used: Claude Code, Opus 4.6

github-actions · 2026-03-09T08:36:38Z

✅ Vale Linting Results

No issues found on modified lines!

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

github-actions · 2026-03-09T08:38:46Z

🔍 Preview links for changed docs

idegtiarenko · 2026-03-10T12:17:37Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+The default behavior is to query across the origin project and all linked projects automatically.
+The following example queries the `data` index and includes the `_index` metadata field to identify which project each result came from:
+
+```esql


NIT: technically this is a rest request, not sure if we mark them differently

explore-analyze/cross-project-search/cross-project-search-esql.md

idegtiarenko · 2026-03-10T12:30:47Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+1. `data` is resolved across all projects. `_origin:logs` is resolved only in the origin project.
+
+::::{tip}
+Error handling differs between expression types. Unqualified expressions fail only if the index exists in none of the searched projects. Qualified expressions fail if the index is missing from the targeted project, regardless of whether it exists elsewhere.


in none of the searched projects -> in none of the linked projects
searched sounds ambiguous to me. Should we rename it to linked?

But "linked" is not right. It also includes origin. So the change suggested by Ievgen would be less correct than what is already there.

left as-is for moment

explore-analyze/cross-project-search/cross-project-search-esql.md

szabosteve

I left some tiny comments; please take or leave them. LGTM!

explore-analyze/cross-project-search/cross-project-search-esql.md

quux00 · 2026-03-10T17:44:00Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+
+:::{note}
+Project routing expressions use Lucene query syntax. The `:` operator matches a tag value, equivalent to `=` in other query languages. For example, `_alias:my-project` matches projects whose alias is `my-project`.
+:::


Good. Thanks for adding this!

explore-analyze/cross-project-search/cross-project-search-esql.md

- Use {{cps-init}} instead of CPS in "Before you begin" - Use "scope" terminology instead of "filtering" for project-level selection - "project identifier" → "project alias" in search expressions intro - Mark REST API request blocks as console instead of esql/json - Add include_execution_metadata: true to default query example - Link SET command docs; clarify SET-first rule and multi-param ordering - Project routing: "excluded projects are never queried" - Add WHERE caveat with link to dedicated section in metadata bullet - WHERE tip: "To optimize a query" instead of "To prevent unnecessary queries" - Replace single-project routing+METADATA example with multi-project _alias:*linked* example - Limitations: remove "in esql" qualifier; "Initially" instead of "Currently"

leemthompo · 2026-03-11T13:07:23Z

@idegtiarenko @szabosteve @quux00 thanks all for the thorough review! 6709404 should address all the feedback

lmk if anything looks off

naj-h

@leemthompo the doc is pretty clear. But like you pointed out in the issue, there are repetitions with other docs like https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5402/explore-analyze/cross-project-search/cross-project-search-project-routing#creating-and-managing-named-project-routing-expressions
If we really want to have an ESQL-specific page, then I think we should probably not repeat the content listed in the other pages that are listed the main CPS page as those are language agnostic (like project routing and tags)

naj-h · 2026-03-11T14:16:45Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+
+Both options support referencing a named project routing expression using the `@` prefix.
+Before you can reference a named expression, you must create it using the `_project_routing` API.
+For instructions, refer to [Using named project routing expressions](/explore-analyze/cross-project-search/cross-project-search-project-routing.md#named-routing-expressions).


should rather link to https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5402/explore-analyze/cross-project-search/cross-project-search-project-routing#creating-and-managing-named-project-routing-expressions which explains how to create them

naj-h · 2026-03-11T14:23:56Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+1. `data` is resolved across all projects except the origin project.
+
+::::{note}
+`*:` in {{cps-init}} does not behave like `*:` in cross-cluster search (CCS):


a Serverless customer might not know what CCS is, so probably worth linking to a doc or at least specify that it is a feature available in stateful deployments

naj-h · 2026-03-11T14:38:18Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+
+- **[Query all projects](#query-all-projects-default)**: If you just want to query across all linked projects, no special syntax is required. Queries automatically run against the origin and all linked projects by default.
+- **[Use project routing](#use-project-routing)**: Use project routing to limit the scope of your search to specific projects before query execution. Excluded projects are not queried.
+- **[Use search expressions](#use-search-expressions)**: Use search expressions for fine-grained control over which projects and indices are queried, by qualifying index names with a project alias. Search expressions can be used independently or combined with project routing.


@quux00 @szabosteve @leemthompo probably a nit - but I realize that we've been calling this Search expressions (qualified/unqualified search expressions) in this doc and the previous ones. It sounds a bit off to me, as internally we've been calling this "qualified/unqualified index expressions", which makes more sense to me as these are the index expressions parts of the request. Search expression sounds more broad. Any thoughts?

sounds good I think we can tighten up the core definition of qualified/unqualified expressions too to be clearer 👍

updated in 8e9d245

leemthompo · 2026-03-11T16:26:47Z

But like you pointed out in the issue, there are repetitions with other docs like https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5402/explore-analyze/cross-project-search/cross-project-search-project-routing#creating-and-managing-named-project-routing-expressions
If we really want to have an ESQL-specific page, then I think we should probably not repeat the content listed in the other pages that are listed the main CPS page as those are language agnostic (like project routing and tags)

definitely true @naj-h just felt like there was enough ESQL-specific info to warrant its own page, and I tried to keep repetition to a minimum, but was a necessary evil to introduce some of the sections

I'll be closing and recreating this PR in Elasticsearch repo to live alongside the rest of the ESQL docs —I'll make sure you have time to look at that again, and we can trim stuff there if we feel it's important

quux00 · 2026-03-12T16:54:33Z

explore-analyze/cross-project-search/cross-project-search-esql.md

+| STATS COUNT(*)
+```
+
+1. Routes the query to projects whose alias is `my-project`.


nit: "projects" should probably not be plural here since there is no wildcard in the alias project routing. So either:

(1) change the project_routing to be _alias:my-project* and in the note say " Routes the query to projects whose alias starts with my-project.

(2) change the note to say: " Routes the query to the project with alias is my-project"

quux00

LGTM. One minor nit suggestion left.

Add ESQL CPS doc

45e1768

leemthompo self-assigned this Mar 9, 2026

github-actions bot deployed to docs-preview March 9, 2026 08:36 View deployment

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

szabosteve approved these changes Mar 10, 2026

View reviewed changes

idegtiarenko reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

quux00 reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

quux00 reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Outdated Show resolved Hide resolved

quux00 reviewed Mar 10, 2026

View reviewed changes

explore-analyze/cross-project-search/cross-project-search-esql.md Show resolved Hide resolved

github-actions bot had a problem deploying to docs-preview March 11, 2026 13:07 Failure

Move SET directive rules into prose, simplify callout

012775b

github-actions bot deployed to docs-preview March 11, 2026 13:59 View deployment

naj-h self-requested a review March 11, 2026 14:16

naj-h reviewed Mar 11, 2026

View reviewed changes

@naj-h's fixes

8e9d245

github-actions bot deployed to docs-preview March 11, 2026 17:32 View deployment

quux00 reviewed Mar 12, 2026

View reviewed changes

quux00 approved these changes Mar 12, 2026

View reviewed changes

leemthompo mentioned this pull request Mar 13, 2026

Document ES|QL SET directive: unmapped_fields and approximation settings #5455

Draft

2 tasks

fix plural

7baf1c6

github-actions bot had a problem deploying to docs-preview March 13, 2026 11:26 Failure

formatting

01a70b5

github-actions bot deployed to docs-preview March 13, 2026 12:05 View deployment

Conversation

leemthompo commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue: #4167

Duplication

Generative AI disclosure

Uh oh!

github-actions bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Vale Linting Results

Uh oh!

github-actions bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

szabosteve left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

leemthompo commented Mar 11, 2026

Uh oh!

naj-h left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo commented Mar 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

quux00 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

leemthompo commented Mar 9, 2026 •

edited

Loading

github-actions bot commented Mar 9, 2026 •

edited

Loading

github-actions bot commented Mar 9, 2026 •

edited

Loading