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

[florent-leborgne]

Summary

This PR addresses #7620 with the following changes to explore-analyze/visualize/custom-visualizations-with-vega.md (section "Writing {{esql}} queries in Vega"):

• "%timefield%" table row: simplified to a single version-neutral line ("The timestamp field to use for the dashboard time range") with a link to the new section below.
• New section #### Apply the dashboard time range to {{esql}} data sources (sibling H4, matching the page's flat reference structure): uses an applies-switch with one tab per behavior, each with an annotated code sample:
  • stack: ga =9.4 — the range applies only through ?_tstart/?_tend; both the parameters and %timefield% are required.
  • stack: ga 9.5+ / serverless: ga — the range applies automatically (as in Lens and Discover); %timefield% is only needed when the time field isn't @timestamp.
  • Closes with a note that time filtering is independent of %context%, and hosts the existing "Event counts over time" worked example (moved here, since it's a time-range example).
• Example intro: reworded so it no longer implies the time range only takes effect through %context%/%timefield%/the parameters. Also corrected "metric" to "line chart" to match the spec.

Time-field resolution (verified against source)

The automatic fallback detects only a field literally named @timestamp (kibana/src/platform/plugins/shared/esql/server/routes/get_timefield.ts, ES_TIMESTAMP_FIELD_NAME = '@timestamp' + fieldCaps), or the field the query compares against ?_tstart/?_tend (parseTimeFieldFromESQLQuery). Indices whose time field has another name (for example timestamp in the flights sample data) are not auto-filtered unless %timefield% is set. The docs call this out so users don't expect auto-filtering on non-@timestamp indices.

All claims 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 (passes).

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: not started.

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.