[florent-leborgne]

Summary

This PR is part of #4898. It restructures the Discover docs around what readers want to do. The 525-line "Explore fields and data with Discover" tutorial becomes a "How Discover works" page, and its other content moves to pages that each do one job. Each query mode gets a short hub about how to query in that mode, and the remaining pages are grouped by job under two new parent pages. The Discover page becomes a hub that points readers to the right page. It targets the #9013 branch until that PR merges. This change supports several elements:

• ES|QL mode becoming the default means the core discover docs should not be super focused on data views and KQL anymore, and that users would benefit from dedicated guidance about the ES|QL mode and how its queries shape your Discover experience.
• The current structure reflects Discover as it was a few years ago. While the core functionality is still there, the UX has evolved and been enriched, making users successful in their adoption and usage of Discover requires an up to date guidance and learning path
• We have more telemetry than we used to have and can adapt the scope of some pages not to only describe the UI but to match some user goals
• The previous "get-started" page had become a long list of capabilities, and kept growing without a clear purpose over the years with new functionality

The navigation under Discover now looks like this with this PR:

Discover
├─ How Discover works
├─ Switch between ES|QL and classic mode in Discover
├─ Explore your data in Discover (new)
│   └─ fields, documents, compare, relevance, grouped results, change points,
│      AI analysis, pattern analysis, field statistics, visualize a field
├─ How to query in Discover's ES|QL mode
│   └─ first-query tutorial, browse sources, results, variable controls, lookup indices
├─ How to query in Discover's classic mode
│   └─ search and filter, runtime fields
└─ Manage your Discover view and sessions (new)
    └─ customize the view, tabs, save and manage sessions, export,
       sessions in dashboards, copy and share, background search, alert rule

Hub and foundations

• explore-analyze/discover.md: now a hub. A "Where to start" list points to the foundations page and the first-query tutorial. Four goal groups follow: query your data, understand your data, shape what your queries return and show, and save and share your explorations. Tasks that work in only one mode name it.
• explore-analyze/discover/discover-get-started.md also gains a short tip in the query modes section that recommends ES|QL mode and says why. The hub's "Where to start" list adds a starting point for classic mode.
• explore-analyze/discover/discover-get-started.md: now "How Discover works" (overview, same URL). It explains what you see on screen, the two query modes, the context-aware experiences by where you open Discover from, the ways to save, share, and export what you find, and how you can arrive with a query already set from a dashboard panel or a shared link. The default mode for each version now lives in switch-esql-mode.md.

Mode hubs and mode-only pages

• use-esql.md and use-classic-mode.md: retitled "How to query in Discover's ES|QL mode" and "How to query in Discover's classic mode". Each introduces its mode and links the pages about writing and refining queries in it.
• Classic-only pages: search-and-filter-classic.md, add-fields-to-data-views.md, visualize-field.md, show-field-statistics.md, and run-pattern-analysis-discover.md state in Before you begin that Discover must be in classic mode. search-and-filter-classic.md also holds the steps to select a data view and a time range.
• ES|QL-only pages: inspect-grouped-stats.md, detect-change-points.md, and analyze-discover-data-with-ai.md state in Before you begin that Discover must be in ES|QL mode.

Two new parent pages

• explore-data.md: "Explore your data in Discover". It lists the pages about understanding results and marks the ones that work in only one mode.
• manage-discover.md: "Manage your Discover view and sessions". It lists the pages under two headings: setting up your workspace, and saving and sharing your explorations.

Pages moved from the tutorial, or new

• explore-fields.md, inspect-documents.md, compare-documents.md, copy-and-share-documents.md, work-with-tabs.md, generate-alerts-from-discover.md, analyze-discover-data-with-ai.md, search-and-filter-classic.md, add-fields-to-data-views.md, visualize-field.md: split out of the tutorial.
• inspect-documents.md: also holds the classic-only actions to open a document on its own page or see the documents around it.
• explore-fields.md: adds the Add breakdown action, which splits the chart by a field.
• discover-search-for-relevance.md: has synced tabs for ES|QL mode and classic mode, with an ES|QL example.
• add-fields-to-data-views.md: lists every option of the runtime field editor and the supported field types.
• troubleshoot/kibana/discover-empty-fields.md: the empty fields FAQ from the tutorial, as a troubleshooting page.
• explore-analyze/_snippets/discover-cancel-query.md: the cancel-query text that applies to every query type, included in esql-results.md and search-and-filter-classic.md. esql-results.md also gets the partial results note.

Saved sessions

• save-open-search.md is split into three pages. It keeps saving and duplicating, and gains a section about opening and finding saved sessions. export-discover-session.md (new) holds the CSV and JSON exports. use-sessions-in-dashboards.md (new) holds the dashboard flows. The moved text is unchanged except for corrections to the privileges, the serverless CSV limits, and the UI labels and entry points in the dashboard flows.
• The session, export, dashboard, and alert rule pages list the privileges each action needs in Before you begin.

Accuracy corrections

• Labels, privileges, limits, and per-version menu paths on the moved and new pages were checked against the Kibana source. Examples: the Store Background search sub-feature, the ES|QL row and column limits, lookup index privileges, variable control rules, and tab behavior.
• The shared variable control snippet now explains the ? and ?? prefixes. esql-variable-controls.md, visualize/add-variable-controls.md, and query-filter/languages/esql-kibana.md include it.
• The CSV export step on export-discover-session.md, and the matching steps in report-and-share.md and automating-report-generation.md, describe the export action and the names it has in each version, including the More menu.
• Version limits that were written as prose are now applies_to tags: MV_INTERSECTS, the TS_INFO and METRICS_INFO exclusion for grouped results, creating an alerting v2 rule from Discover, and Hide null fields in classic mode.
• The check for which context-aware experience is active is now part of the context-aware section on discover-get-started.md. inspect-documents.md covers documents and requests.
• Smaller fixes checked against the Kibana source: the 100-result compare limit, the range of the Sample size option, the Generate CSV button, the Add filter label, the Pin summary option for the Summary column, and the permission needed to create a categorization job from Patterns. Reader-facing additions: filter examples that keep one or several values in the ES|QL tutorial, an EVAL section on the ES|QL results page, with one-line tips that point to it from the runtime field page, a pointer from the Sample size section to the LIMIT command in ES|QL mode, the Discover export page as the target of the hub's export link, a one-line tip that points to ES|QL grouping on the pattern analysis page, and a sentence on what a link recipient sees in the share section. Plain-language replacements for internal terms, a few links between related pages, and a version-grouped list of TS and LIMIT behavior on switch-esql-mode.md are also included.

Titles and structure

• Page titles on the Discover pages mention Discover, and navigation labels stay short.
• Mode-only pages say in Before you begin which mode Discover must be in. The session, export, dashboard, and alert rule pages list the privileges each action needs there too.
• The how-to pages in this section follow the same structure: Before you begin, steps, a Result line, and Next steps.
• The tutorial's "Save your Discover session" section was dropped because save-open-search.md already covers it in full.
• Updated screenshots: the Discover overview (new), the data view menu, and the day_of_week popover. visualize-field.md uses the image directive.

Navigation and links

• redirects.yml, explore-analyze/toc.yml, troubleshoot/toc.yml, and inbound links: every moved anchor has a redirect, and links in this repository point straight to the new pages. Link text that used the old page titles is updated.

Generative AI disclosure

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

• Yes
• No

Tool(s) and model(s) used: Claude Code with Claude Sonnet 5.5. I moved existing text without rewriting it where possible. The hubs, the "How Discover works" page, the two parent pages, and the relevance tabs are new prose. I checked their claims, and the privileges, labels, and limits on the session pages, against the existing pages and the Kibana source.

🤖 Generated with Claude Code

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: completed, no findings. View progress.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

Docs review summary

Issue satisfaction

Partially assessed. The PR is part of #4898 and covers the Discover restructure it describes. This was a sampled pass over a 45-file, 87-commit change, not an exhaustive review of every page.

Review coverage

• Content type: Overview and hub pages (discover.md, discover-get-started.md, explore-data.md, manage-discover.md). The rest are how-to pages and one troubleshooting page.
• Checked: I scanned the changed pages for stacked admonitions and flagged wording such as "please" and "and/or". I found nothing to report. I read the PR description and the Vale output counts. I did not read every changed page line by line.
• Not checked: Technical accuracy of UI labels, privileges, and limits was not verified against the Kibana source, so UI labels: not verified. The cross-repo contradiction check against published docs was not run. The per-page applies_to review was not done in depth.

Generated from Docs review agent · ◷

Was this review helpful? When the PR closes, add the label ai-review:helpful or ai-review:unhelpful to it.

[bmorelli25]

Thoughts in no particular order:

I'm left wondering why I would want to use one mode or the other. The changes do a great job explaining what each mode is and how it works, but I'm never told when I'd pick one over the other. The ESQL tut is the closest feedback on this topic by saying that I can directly query by name without needing to create a data view first. But then six pages in Before you begin say the other mode doesn't support the feature. So what is our guidance here? Is it --> we want folks to use ESQL? If so , we should say that. Or is it, something like, if you want to run pattern analysis, use classic mode?

The "Where to start" section doesn't really offer a classic getting started guide. Only ESQL. I presume that is by design?

The flow from How it works --> Switch Query mode --> Explore your data makes sense. However, there are three pages in the Explore your data that don't support ES|QL mode while every other page does. It's the last three pages (maybe by design?). But I'm wondering if there's something more we can do here. Are there alternatives to, for example, running a pattern analysis that can be done in ESQL mode? Or is it practical enough to expect a user to switch modes if they want to achieve this?

Manage your view and sessions is kind of a catch all. Settings, tabs, queries, sessions, alert rules. I like the "Save and share your explorations" title that you use on the hub page better. You could use that heading and move the customization and tab stuff to a "Set up your workspace" group.

[florent-leborgne]

ty @bmorelli25, i was thinking about some of these and made a few more changes (minimal) that should address the issues. Some of these are by design indeed.

[alexmarhaba]

LGTM, amazing work @florent-leborgne, thank you!

[florent-leborgne]

Hey there @sddonne, could you check whether this section is ok? I had a chat earlier with @alexmarhaba regarding the changes done in elastic/kibana#296406

Alex mentioned that for logs, this would only work with certain integrations. These are listed directly in the discover-logs page that lives in the discover docs (also in this PR if you want to check, i'll tag you there too)

[florent-leborgne]

(sorry it's a huge PR that restructures some other things but some changes are already stacked and I did want to draft them quickly after chatting with alex about the udpated structure)

[florent-leborgne]

preview since it won't show on a stacked PR:

[florent-leborgne]

cc @sddonne and @alexmarhaba for the logs in classic view case, if you want to check this section.

[bmorelli25]

Thanks for adding the mode guidance and classic vs ES|QL alternatives when the exist. Really nice improvements here. High level looks good. Let me know if you want me to dig into the details more.