docs: Vega ES|QL data sources respect the dashboard time range (#7620)

[florent-leborgne]

Summary

Hey @mbondyra - I thought this change deserved a bit of explanations in the docs, especially to clarify the 9.4 vs. 9.5 behavior. I tested what I wrote (and simplified some bits like the value to put in %timefield% for 9.4 which could actually be anything IIUC) but let me know if there's something more nuanced or not as accurate as I'd hoped :D Thank you 🙏

From 9.5 (and in serverless), the dashboard time range applies to Vega and Vega-Lite {{esql}} data sources automatically, like Lens and Discover (kibana#280070). The Vega reference previously stated that %timefield% only enables the ?_tstart/?_tend parameters, which no longer describes the behavior. This PR updates that reference and adds a dedicated section explaining how the time range is applied per version.

All changes are in explore-analyze/visualize/custom-visualizations-with-vega.md:

• %timefield% parameter table row: replaced "When set, enables the ?_tstart and ?_tend named parameters..." with "The timestamp field to use for the dashboard time range", plus a link to the new section.
• New section "Apply the dashboard time range to {{esql}} data sources" (stack: ga 9.4, serverless: ga): an applies-switch with one tab per behavior, each with an annotated example:
  • stack: ga 9.5+ / serverless: ga: the range applies automatically. The time field defaults to @timestamp; set %timefield% or reference the field with ?_tstart/?_tend to use another. Notes that the parameters are still substituted when present, and that time filtering is separate from %context%.
  • stack: ga =9.4: the range applies only through ?_tstart/?_tend, which %timefield% turns on; both are required.
• Worked line-chart example: moved into the new section, with its intro reworded to explain it wires the time range explicitly so it works the same in every version (previously it was described as a "metric" and implied the range only takes effect through %context%/%timefield%/the parameters).
• Fast mode note: now closes the "Writing {{esql}} queries in Vega" section, since the time-range material became its own section.
• {{esql}} tutorial callout: reworded the %timefield% annotation from "Enables the ?_tstart and ?_tend named parameters..." to "Sets @timestamp as the time field for the dashboard time range", so the tutorial matches the new reference section.

Behavior, verified against source

When %timefield% isn't set, the time field resolves to the field the query compares against ?_tstart/?_tend (parseTimeFieldFromESQLQuery), otherwise a field literally named @timestamp (get_timefield.ts: ES_TIMESTAMP_FIELD_NAME + fieldCaps), otherwise none. Indices whose time field has another name (for example timestamp in the flights sample data) are not auto-filtered unless %timefield% is set, which the new section calls out. The DSL range filter and the ?_tstart/?_tend substitution are independent mechanisms and can both apply.

Verified against esql_query_parser.ts, get_time_field.ts, get_timefield.ts, and query_parsing_helpers.ts at HEAD (kibana#280070 and its 9.5 backport #280113). Built locally with docs-builder --strict (0 errors, 0 warnings).

Resolves

Closes #7620

---

AI-generated draft — created with Claude Opus 4.8.
Review all generated content for factual accuracy before merging.

[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. View progress.

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

[github-actions]

🔍 Preview links for changed docs

• explore-analyze/visualize/custom-visualizations-with-vega.md

[github-actions]

✅ Elastic Docs Style Checker (Vale)

No 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.

[github-actions]

Docs review summary

Focus areas

• Style and clarity: The new/edited content (the %timefield% table cell, the new Apply the dashboard time range to {{esql}} data sources subsection, and the reworded line-chart intro) reads clearly, uses active voice/present tense, and avoids discouraged word choices. No new style-guide violations found in the touched lines.
• Jargon: No unexplained Elastic-internal jargon introduced. "Lens" and "Discover" are already used elsewhere on the page for the same comparison, so no new context is needed.
• Frontmatter and applies_to: Frontmatter is unchanged by this PR. The new applies-switch/applies-item blocks (stack: ga 9.5+, serverless: ga and stack: ga =9.4) follow the same syntax pattern used elsewhere in this file and repo, and correctly scope the exact-version case to 9.4 (matching that the {{esql}} Vega data source itself only shipped in 9.4, per the outer stack: ga 9.4 wrapper).
• Content type fit: This is a reference page; the new subsection with annotated worked examples matches the pattern already used in neighboring reference subsections (for example the existing {{esql}} tutorial and query sections), so it doesn't clash with the page's established structure.
• Parent issue satisfaction: Satisfied. Issue Vega panels with ES|QL data sources now respect the dashboard time range #7620 asked for an updated %timefield% description, an explanation of the time-field resolution order, a note that filtering is independent of %context%, and preserved 9.4 behavior with lightest-touch applies_to scoping. The PR delivers all of this via the new #vega-esql-time-range section and updated table row/callout.

Notes

• All 12 pre-fetched Vale findings (lines 424, 436, 1209, 1225, 1266, 1267, 1391, 1395, 1590, 1790, plus the mapped_pages warning at line 2) fall on pre-existing lines outside this PR's two diff hunks (~114–120 and ~1426–1538), so they were intentionally not flagged here per the pre-existing-issue policy for PR reviews.

Generated by Docs review agent for #7678 · sonnet50 68.4 AIC · ⌖ 6.47 AIC · ⊞ 15.7K · ◷

[mdbirnstiehl]

A couple of suggestions for your consideration, otherwise LGTM

[mdbirnstiehl]

Suggested change

	To filter on a different date field, specify it in one of the following ways:
	To filter on a different time field, specify it in one of the following ways:

just for consistency with the paragraph preceding this line.

[mdbirnstiehl]

Suggested change

	{{kib}} applies the dashboard time range automatically, the same way it does in Lens and Discover. By default, it looks for a field named `@timestamp` in your data and filters on it, so no configuration is needed when your time field has that name.
	{{kib}} applies the dashboard time range automatically, the same way it does in Lens and Discover. By default, it looks for and filters on the `@timestamp` field, so no configuration is needed when your time field is named `@timestamp`.

[mdbirnstiehl]

Suggested change

	If your data has no `@timestamp` field and you don't specify one, the query isn't filtered by time.
	If your data has no `@timestamp` field and you don't specify a different time field, the query isn't filtered by time.