elastic / elastic/docs-content
ES|QL BUCKET function documentation should show Kibana time picker variables
- 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.