elastic / elastic/docs-content

ES|QL BUCKET function documentation should show Kibana time picker variables

Open
#5,066 2 comments 0 reactions 0 assignees View on GitHub
enhancement Team:Developer Team:Experience
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 17h
Merged PRs (30d)
130

Description

## Summary

The ES|QL BUCKET function documentation in the Quick Reference (shown in Kibana Discover) should include an example demonstrating how to use Kibana time picker variables (`?_tstart` and `?_tend`) with the BUCKET function.

## Current State

The current BUCKET documentation shows examples with hardcoded date strings:

```esql
FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
```

## Suggested Addition

Add an example showing how to use Kibana's time picker integration with named parameters:

```esql
FROM kibana_sample_data_logs
| STATS avg_bytes = AVG(bytes)
BY BUCKET(@timestamp, 50, ?_tstart, ?_tend)
```

This syntax allows the BUCKET function to dynamically use the time range selected in Kibana's time picker, which is a common use case for users working in Discover.

## Why This Matters

1. **Common use case**: Users frequently want to bucket data based on the selected time range in Kibana
2. **Discoverability**: The `?_tstart` and `?_tend` named parameters are not intuitive and users may not know they exist
3. **Consistency**: Other time-based ES|QL features should document their integration with Kibana's time picker

## Technical Context

- Kibana uses the named parameters `?_tstart` and `?_tend` to pass time picker values to ES|QL queries
- This is handled in Kibana's `query_parsing_helpers.ts` via the `getTimeFieldFromESQLQuery` function
- The documentation is generated from Elasticsearch source docs and displayed in Kibana's Quick Reference panel

## Related

- Kibana source: `src/platform/packages/shared/kbn-esql-utils/src/utils/query_parsing_helpers.ts`
- Documentation generation: `src/platform/packages/private/kbn-language-documentation/scripts/generate_esql_docs.ts`

## More contexte (internal)
https://elastic.slack.com/archives/C02TBFZFYSD/p1770404232607559

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.