docs: turn Discover Try ES|QL into a tutorial and ES|QL hub (#4890) - #8392
Draft
florent-leborgne wants to merge 4 commits into
Draft
florent-leborgne wants to merge 4 commits into
florent-leborgne wants to merge 4 commits into
Conversation
…4890) Keep the published try-esql URL as a standalone first session, and move leftover Discover+ES|QL jobs onto a mode hub with lookup and grouped STATS children. AI-Assisted: Cursor Grok 4.6 Co-authored-by: Cursor <cursoragent@cursor.com>
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
Contributor
Elastic Docs Style Checker (Vale)Summary: 2 warnings found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/discover/browse-esql-sources.md | 41 | Elastic.Spelling | 'subqueries' is a possible misspelling. |
| explore-analyze/query-filter/languages/esql-kibana.md | 544 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
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[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Contributor
There was a problem hiding this comment.
Docs review summary
This PR splits the monolithic try-esql.md page into a tutorial (try-esql.md, rewritten in place), a new hub/overview page (use-esql.md), and two new how-to pages (create-lookup-indices.md, inspect-grouped-stats.md), with link retargets across 7 related pages, a toc.yml reorder, and matching redirects.yml fragment redirects.
Criteria
- User focus: Improved. The former single "Using ES|QL" page mixed a first-run walkthrough with dozens of unrelated reference procedures. Splitting it into a short Get started with Discover using ES|QL tutorial plus a task-organized hub gives readers a clearer entry point for each goal.
- Technical accuracy: No inaccuracies found. Spot-checked the
enableESQLdefault-enabled claim intry-esql.mdagainst Query your data with ES|QL in Timeline (consistent: "enabled by default"), and the lookup-index privilege list increate-lookup-indices.mdagainst the existingLOOKUP JOINcross-reference in esql-kibana.md, which already links forward to the new page — the integration is coherent. - Applicability: Every anchor that moved off
try-esql.mdhas a matchingmany:-style fragment redirect inredirects.ymlpointing at the correct destination page, and each destination anchor exists on the target page.toc.ymlordering matches the new page relationships. - Maintainability: Good. Content was relocated rather than duplicated, and the new how-to pages reuse the existing
applies-switchpattern for version-gated procedures rather than forking content. - Language: No jargon issues found — "Discover," "Lens," and ES|QL-related acronyms are all introduced with context on first use per page.
- Style: Vale reported 25 findings across touched files, but only one falls on a line this PR actually changed: a
QuotesPunctuationflag onesql-kibana.md:544. That line is pre-existing{applies_to}markup syntax, not prose Vale is misreading as a quotation — no action needed. - Issue satisfaction: Satisfied. The PR closes #4890 by turning the page into a tutorial with a companion ES|QL hub, matching the issue's ask.
Nits
use-esql.mddeclarestype: overviewin its frontmatter but contains several genuine step-by-step procedures (the 3-variant "Revert to Discover's classic mode"applies-switchblock, and the transcluded variable-control how-to snippets). Per the overview content type guidelines, overviews shouldn't include long procedures. That said, the sibling hub pageesql-kibana.mdfollows the same established mixed pattern in this product area (short embedded procedures inside a broader landing page) without declaring anytypeat all, so this reads as a reasonable, consistent structural choice for this section rather than a page that will send readers looking for a how-to guide. Worth a second look only if this page grows more procedures over time.
Notes
esql-kibana.mdhas notypefrontmatter field at all (pre-existing, not introduced by this PR). Since this PR touches the file for link retargets, it could be a convenient moment to add one, but it's out of scope for this change.
Generated by Docs review agent for #8392 · claude · sonnet · 214.4 AIC · ⊞ 19K
florent-leborgne
left a comment
florent-leborgne
left a comment
Member
Author
There was a problem hiding this comment.
self-review 1
|
|
||
| {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4+` Active filters from the filter bar are also converted to {{esql}} `WHERE` clauses where possible. Filters that can't be converted, such as scripted filters, are dropped. | ||
|
|
||
| {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4+` Discover remembers your last used query mode. The next time you open a new Discover session, it opens in the mode you last used. |
Member
Author
There was a problem hiding this comment.
Suggested change
| {applies_to}`serverless: ga` {applies_to}`stack: ga 9.4+` Discover remembers your last used query mode. The next time you open a new Discover session, it opens in the mode you last used. |
no real value in this information
The hub routes to a job instead of holding every procedure. Sort, limits, and filtering from a value stay on the results how-to. AI-Assisted: Cursor Grok 4.7 Co-authored-by: Cursor <cursoragent@cursor.com>
Discover variable controls are GA since 9.2, with no preview gate in Kibana. The tutorial warns that switching back does not restore the KQL query. AI-Assisted: Cursor Grok 4.7 Co-authored-by: Cursor <cursoragent@cursor.com>
The first mention expands KQL, and the query selects the data. AI-Assisted: Cursor Grok 4.7 Co-authored-by: Cursor <cursoragent@cursor.com>
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
1 participant
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.
Summary
This PR addresses #4890 with the following changes:
explore-analyze/discover/try-esql.md: Standalone tutorial, stable URL. Title is Get started with ES|QL in Discover. First session: open ES|QL mode, query sample logs, filter and sort, save the session. Switching back to classic mode does not restore a converted KQL query. One pointer to putting the session, chart, or table on a dashboard.explore-analyze/discover/use-esql.md: Overview of the Discover tasks that are specific to ES|QL mode. It routes to the jobs. It does not contain the procedures.switch-esql-mode.md: Switch to ES|QL or back to classic, including what happens to a converted query.browse-esql-sources.md: Browse data sources and fields from the editor.esql-results.md: Read the results. Filtering from a value and sorting come first. Columns, limits, the non-@timestamptime field, and a short pointer for keeping the chart or table follow.esql-variable-controls.md: Add variable controls, including multi-value selections and import onto a dashboard. GA since 9.2 (Kibana #229598). No preview flag on currentmain. Multi-value selections stay badged preview.create-lookup-indices.md: Lookup-index editor.inspect-grouped-stats.md: GroupedSTATSresults.explore-analyze/toc.yml,explore-analyze/discover.md: Classic get-started stays first until ES|QL is the default mode. The tutorial is next, then the ES|QL overview.redirects.ymland inbound links: Fragment redirects from the old Try ES|QL anchors, and from the overview, to the job pages.Does not claim ES|QL is Discover's default mode.
discover.isEsqlDefaultstill defaults tofalseat Kibanaorigin/main. The 9.6discover:defaultEsqlQuerysetting remains documented as a starting-query override.Switching from ES|QL back to classic discards the ES|QL query, including one built by converting KQL or Lucene, and opens classic mode with an empty KQL query.
Visualization and session-to-dashboard IA is out of scope. The tutorial and the results page point at Save a Discover session for reuse.
Resolves
Closes #4890
Generative AI disclosure
Tool(s) and model(s) used: Cursor Grok 4.7. Used to restructure and draft. UI labels, defaults, and behavior were checked against
elastic/kibanaatorigin/main.Made with Cursor