docs: add visualization approach decision guidance & improve intros to balance both modes (#5447)#6560
Merged
Merged
Conversation
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
🔍 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. |
Both approaches are Lens — one uses drag-and-drop with data views, the other uses ES|QL queries. Update section heading, intro, anchor, and cross-references accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
florent-leborgne
changed the title
Co-authored-by: Cursor <cursoragent@cursor.com>
Primary section now lives on the Lens page where the decision is most relevant. Replaced use-case rows with a strengths matrix using checkmarks. visualize.md keeps a one-line pointer. Co-authored-by: Cursor <cursoragent@cursor.com>
Rather than a comparison table on lens.md, add a short "particularly useful when" list directly on the ES|QL visualizations page. Users landing on esorql.md now immediately see the scenarios where it shines, with a reverse pointer to Lens for simpler aggregations. Also adds a one-sentence pointer in lens.md and removes the dedicated comparison section from both lens.md and visualize.md. Co-authored-by: Cursor <cursoragent@cursor.com>
Reorder the esorql.md intro so the page opens with the "particularly useful when" context before the how-to entry points — easier to scan for users evaluating whether ES|QL mode is right for them. Also tighten the Lens back-reference to "Lens in point-and-click mode" and remove a spurious trailing blank line from visualize.md. Co-authored-by: Cursor <cursoragent@cursor.com>
Update "drag-and-drop" to "point-and-click" in the Lens page opening line, aligning with new Kibana UI language (kibana#264457). Separate the ES|QL cross-reference into its own paragraph so it's visible to users skimming the intro rather than buried at the end of a sentence. Also adds "prototyping from Discover" as a third trigger scenario for the ES|QL pointer, consistent with esorql.md. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Florent LB <florent.leborgne@elastic.co>
Co-authored-by: Cursor <cursoragent@cursor.com>
Replace the existing intro paragraphs with a concise two-bullet structure that names and describes both modes: point-and-click (data view, no query required) and query (ES|QL or PromQL, for complex and cross-index use cases). Data view setup info moves into the point-and-click bullet. The query bullet links both ES|QL and PromQL docs and points to esorql.md for details. Co-authored-by: Cursor <cursoragent@cursor.com>
florent-leborgne
changed the title
nastasha-solomon
approved these changes
May 25, 2026
| - **Point-and-click**: configure your visualization interactively by selecting fields from a [data view](/explore-analyze/find-and-organize/data-views.md), choosing aggregations, and setting dimensions and display options. No query writing required. Data views are created automatically when you [upload a file](/manage-data/ingest/upload-data-files.md) or [add sample data](/manage-data/ingest/sample-data.md); otherwise, you need to create one manually. | ||
| - **Query**: write an [{{esql}}](elasticsearch://reference/query-languages/esql.md) or [PromQL](elasticsearch://reference/query-languages/esql/commands/promql.md) query to retrieve and transform your data, then configure the visualization on top of the result. Best suited for cross-index queries, complex filtering, and custom calculations. Refer to [ES|QL visualizations](esorql.md) for details. | ||
|
|
||
| :::{agent-skill} |
Member
There was a problem hiding this comment.
Outside the scope of this PR, but sharing in case it's worth considering: Since this skill helps users build the visualizations described in the following table, it might be more appropriate to place it after the table instead of before it. Up to you!
|
|
||
| # ES|QL visualizations [esql-visualizations] | ||
|
|
||
| Creating visualizations using an {{esql}} query is particularly useful when you need to: |
Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.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
2 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.
Closes #5447
Summary
Adds decision guidance for users choosing between Lens's point-and-click mode (data views) and ES|QL mode for building visualizations.
Rather than a comparison table, the guidance is placed where it's most useful: the introduction of the ES|QL visualizations page. Users landing on
esorql.mdnow immediately see the scenarios where ES|QL mode shines, plus a reverse pointer to Lens for simpler cases.Changes:
esorql.md: adds "particularly useful when" bullet list (cross-index queries, complex filtering, prototyping from Discover) + reverse pointer to Lenslens.md: adds one-sentence pointer to ES|QL visualizations for complex/cross-index use cases; removes comparison sectionvisualize.md: removes comparison section added in earlier iteration (net zero change from original)More work on bringing ES|QL/Query mode more naturally up in docs will be carried as it also becomes more prominent an integrated over time in the UI
Checklist
kibana-dashboardsskill and Kibana API (data_view_referencevsesqlusage patterns)