docs: document KQL and natural language query drafting in the ES|QL editor (#6350)#6692
Open
florent-leborgne wants to merge 22 commits into
Open
docs: document KQL and natural language query drafting in the ES|QL editor (#6350)#6692florent-leborgne wants to merge 22 commits into
florent-leborgne wants to merge 22 commits into
Conversation
Restructure the Quick search section to introduce a Natural language mode alongside KQL. Available from 9.5 with an Enterprise license and a configured LLM connector. 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. |
The Quick search button renders as icon-only when editor space is reduced, so the visible bold "Quick search" label alone is hard to find. Co-authored-by: Cursor <cursoragent@cursor.com>
The Quick search entry point is an icon-only button in the editor
toolbar, not a text-labeled button. When natural language is available,
the icon switches to a custom magnify-with-sparkles SVG and the tooltip
reflects that. Drop the fake bold label and the inaccurate {icon}
directive that did not match either UI state, and call out the sparkles
variant in the NL section so readers recognize it.
Co-authored-by: Cursor <cursoragent@cursor.com>
Add the {icon}`magnify` glyph to the intro to match the plain icon
state, and {icon}`sparkles` to the NL note. The custom Kibana
magnify-with-sparkles SVG is not part of the EUI icon set, so render it
in two parts via the icons available in docs-builder.
Co-authored-by: Cursor <cursoragent@cursor.com>
'Quick search' is an internal Kibana code name and does not appear in the product UI. Rename the section to 'Draft queries with KQL or natural language', change the anchor to esql-kibana-search-bar, and replace every 'Quick search' reference in prose with 'the search bar'. Co-authored-by: Cursor <cursoragent@cursor.com>
florent-leborgne
changed the title
Switches the NL-enabled state description from a magnify+sparkles combo to the single magnify_sparkles glyph added in elastic/docs-builder#3378. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Florent LB <florent.leborgne@elastic.co>
- Section title: "Create queries from..." → "Build queries with..."
- Prose: "get a query" → "build a query" for readability
- NL subsection anchor: esql-kibana-search-bar-nl → esql-kibana-quick-search-nl
to match the preserved parent anchor
- Image alt: literal "ES|QL" instead of {{esql}} substitution, matching
the existing KQL image
Co-authored-by: Cursor <cursoragent@cursor.com>
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
-> Requires elastic/docs-builder#3378 to land first for the updated icons used in the NL section. Until then, CI will fail.
This PR addresses #6350 with the following changes to
explore-analyze/query-filter/languages/esql-kibana.md:### Free-text quick searchto### Build queries with KQL or natural language. The previous title relied on "Quick search", which is an internal Kibana code name and never appears in the product UI.#### Filter your data with KQLand#### Generate a query from natural language), so KQL stays available on 9.3+ and the natural-language mode is documented as a new preview capability on 9.5+ and on serverless.esql-kibana-quick-searchanchor on the parent section to avoid breaking external links (Kibana code, blog posts, other docs). The new NL subsection uses the consistentesql-kibana-quick-search-nlanchor.**Quick search**bold pseudo-label from prose. The trigger button inESQLMenuis icon-only with no visible text label; the only "Quick search" string was on aQuickSearchActionfooter button that has been dead code since the Feb 2026 editor redesign (PR #251223).{icon}`magnify`for the trigger (matches the plain icon state seen by users without natural-language access) and{icon}`magnify_sparkles`in the NL section to match the sparkles-magnify glyph shown in product when natural language is enabled. The glyph is a custom Kibana SVG (MagnifySparklesIcon); it has been added to docs-builder in Sync EUI icon library with Jan–May 2026 renames and additions docs-builder#3378 so it can be rendered via the{icon}directive.Key factual notes the issue body got wrong:
esql.nlToEsqlEnabled), not an advanced setting. Since the flag was never documented publicly, there is no "advanced setting instruction" to remove; the change is purely additive.use_nl_to_esql_check.ts(license.hasAtLeast('enterprise')).techPreviewTooltipineditor_visor/index.tsx), so the docs usepreviewrather thangafor the new content.No AI connector configuredotherwise (nl_to_esql_route.ts).buildNlToEsqlAdditionalContextinnl_to_esql_route.ts), so I added a tip about follow-up requests.Resolves
Closes #6350
Screenshots
explore-analyze/images/kibana-esql-search-bar-nl.pngto the newGenerate a query from natural languagesubsection, showing the mode selector open with Natural language selected and a sample prompt running against sample data.esql-quick-search-kql.gif) is kept as-is in the KQL subsection. For users without an Enterprise license, the search icon stays as the plain magnify glyph and the mode selector is hidden, so the GIF still accurately reflects what they see — no update needed.