Document grouped results layout and CATEGORIZE patterns in Discover ES|QL#6190
Merged
Conversation
…5733) Add a new section to the ES|QL tutorial covering the grouped results layout that appears for STATS BY queries with a single grouping field, including the Group by selector, CATEGORIZE pattern rendering, SPARKLINE rendering, and row actions. Add a reciprocal pointer from the classic Patterns analysis page. Made-with: Cursor
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
Contributor
🔍 Preview links for changed docs |
Contributor
✅ Vale Linting ResultsNo 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. |
- Note that BUCKET and TBUCKET in BY don't trigger the grouped layout (only single-field grouping or CATEGORIZE), per SUPPORTED_STATS_COMMAND_OPTION_FUNCTIONS in kbn-esql-utils. - Add three screenshot TODO placeholders covering the overview, the CATEGORIZE+SPARKLINE row, and the row actions menu. Carries over the BUCKET/TBUCKET caveat from #5457 so it can be closed as superseded. Made-with: Cursor
florent-leborgne
changed the title
2 tasks
…s, fix counter term Made-with: Cursor
…nt scaling tip Made-with: Cursor
Made-with: Cursor
…KLINE row Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Member
Author
|
Reviewers, this PR mixes a few things together:
That was I think easier to handle this way. Please let me know what you think or what else you'd like to see there. I tested the feature locally on a 9.4 build to take the screenshots - let me know if everything seems in order there. |
Member
Author
|
Sparkline is actually not going to land in 9.4 so I'll rework that part |
SPARKLINE was deferred from 9.4 to a later release. Replace the combined CATEGORIZE+SPARKLINE example with a CATEGORIZE-only example, comment out the SPARKLINE paragraph, query, sampling tip, and screenshot using a clearly-marked 'RESTORE FOR 9.5' block, and drop the sparkline mention from the reciprocal tip on the pattern analysis page. Tracked in #6215. Made-with: Cursor
florent-leborgne
changed the title
benironside
approved these changes
May 4, 2026
Contributor
benironside
left a comment
benironside
left a comment
There was a problem hiding this comment.
My only suggestions are nits. Approving!
Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Co-authored-by: Florent LB <florent.leborgne@elastic.co>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⛔ Hold for release
Do not merge before all of the following ship:
Until those gates are met, the cascade layout is invisible on production Serverless and ECH, even though the supporting Kibana code has shipped.
Summary
Documents the ES|QL
CATEGORIZEUX enhancements that ship in Kibana 9.4 and Serverless preview:explore-analyze/discover/try-esql.mdcovering:STATS BYqueries with a single grouping field.BUCKET/TBUCKETand multi-field exclusion.CATEGORIZEpattern token rendering, with a single-query example.explore-analyze/discover/run-pattern-analysis-discover.md) pointing to the new ES|QL section.Closes #5733.
Supersedes #5457 (carries over the BUCKET/TBUCKET caveat as a single-paragraph clarification).
SPARKLINE deferral
SPARKLINEwas originally part of this PR but has been deferred from 9.4 to 9.5. The combinedCATEGORIZE+SPARKLINEexample, theSAMPLEscaling tip, and the sparkline screenshot are commented out in the markdown source inside a clearly-markedRESTORE FOR 9.5block. The reciprocal tip on the pattern analysis page no longer mentions sparklines. Restore work is tracked in #6215.Verification
All scenarios still in scope verified on a local 9.4 snapshot Kibana + Elasticsearch build with a Trial license:
STATS BYtriggers the grouped layout with the Group by selector and "N groups" results count.STATS BYfalls back to the flat table.BUCKET/TBUCKETgrouping queries fall back to the flat table.CATEGORIZErenders patterns with token highlighting.(
CATEGORIZE+SPARKLINEwas also verified on the local snapshot build before the SPARKLINE content was deferred.)Source verification
Cross-checked against
elastic/kibanamainand the9.4branch:isCascadedDocumentsVisible,SUPPORTED_CASCADE_GROUPING_COUNT = 1) incascaded_documents_provider.tsx.trueinbuild_services.ts, set byelastic/kibana#260698and present on the 9.4 branch.SUPPORTED_STATS_COMMAND_OPTION_FUNCTIONS = ['categorize']inkbn-esql-utils/src/utils/cascaded_documents_helpers/utils.ts(this is why BUCKET/TBUCKET don't trigger the cascade).use_row_header_components.tsxanduse_table_header_components.tsx.Screenshots
One screenshot placeholder is inline in the diff as a commented-out image directive:
The previously-planned
CATEGORIZE+SPARKLINErow screenshot is commented out alongside the SPARKLINE content; it will be restored as part of #6215.Note on supersession
This PR replaces #6086 (which couldn't be reopened because the branch HEAD has moved past the closed-state ref). The same branch (
docs-issue-5733-categorize-ux) is reused. #6086 is left closed for history.Generative AI disclosure