ESQL: TRange timezone support by ivancea · Pull Request #139911 · elastic/elasticsearch

ivancea · 2025-12-22T17:48:11Z

Added timezone support to TRange(<date_period>). Now a TRange(-1d) will honor DST
Changed the Configuration.now field to be a constructor param. Currently, it was created inside, which made testing harder
- Also changed it to be an Instant instead of a ZonedDateTime. It was also converted back to an instant, and there's no meaning in a zone here, as it's an absolute point in time. Plus there's a separated "zoneId" field.

…expected values in tests

elasticsearchmachine · 2025-12-22T17:48:48Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2025-12-22T17:48:49Z

Hi @ivancea, I've created a changelog YAML for you.

github-actions · 2025-12-22T17:50:44Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

ivancea · 2025-12-22T17:54:12Z

.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/TRange.java

            value = literal.fold(FoldContext.small());
        }

-        if (value instanceof Instant instantValue) {


This was only being reached by the tests, which were inserting Instants as params. This should never happen in production code, so I instead fixed the tests and removed this from here

ivancea · 2025-12-22T17:56:40Z

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/Configuration.java

        String projectRouting
    ) {
        this.zoneId = zi.normalized();
-        this.now = ZonedDateTime.now(Clock.tick(Clock.system(zoneId), Duration.ofNanos(1)));


This line was moved as-is to EsqlSession, which is the only place where a productive Configuration is created.

For other usages in tests, I used either Instant.now() or randomInstant()

ivancea · 2025-12-22T17:59:23Z

.../src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/TRangeTests.java

+                    DataType.DATE_PERIOD,
+                    Period.ofDays(1),
+                    timestampDataType,
+                    parse("2020-02-03T10:11:12.123456780Z"),


For easier reviewing, those parse() dates are, in this order:

The row timestamp to be evaluated

The "now" configuration value (Which is the "end" of the range, and the reference point for the date period maths

An expected start date, to double-check that the "now - period" math is correct

ivancea · 2025-12-22T18:00:19Z

.../src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/TRangeTests.java

-        Clock fixedClock = Clock.fixed(fixedNow.toInstant(), fixedNow.getZone().normalized());
-        ZonedDateTime fixedNow = ZonedDateTime.now(Clock.tick(fixedClock, Duration.ofNanos(1)));
-
-        Configuration spyConfig = Mockito.spy(configuration);
-        Mockito.doReturn(fixedNow).when(spyConfig).now();


No need to mock the "now" anymore!

ivancea · 2025-12-22T18:01:59Z

I'm open to move the configuration change to another PR. It's just that this PR tests depend on it, and the changes were quite straightforward. Open to opinions

luigidellaquila

Thanks @ivancea, the general behavior is correct, so it LGTM

I only have a concern about how we declare support for keyword parameters, see comments below

luigidellaquila · 2026-01-08T08:54:46Z

docs/reference/query-languages/esql/_snippets/functions/types/trange.md

 | date | date | boolean |
 | date_nanos | date_nanos | boolean |
 | date_period | | boolean |
-| keyword | keyword | boolean |


This is a side effect of relying on implicit casting.
If we don't have tests for the KEYWORD type we'll lose this information. I'm not sure we want it.

luigidellaquila · 2026-01-08T08:55:11Z

docs/reference/query-languages/esql/_snippets/functions/parameters/trange.md

 **Parameters**

 `start_time_or_offset`
-:    Offset from NOW for the single parameter mode. Start time for two parameter mode.  In two parameter mode, the start time value can be a date string, date, date_nanos or epoch milliseconds. 


luigidellaquila · 2026-01-08T09:31:00Z

docs/reference/query-languages/esql/kibana/definition/functions/trange.json

-      "params" : [
-        {
-          "name" : "start_time_or_offset",
-          "type" : "keyword",


Will Kibana report an error now in case we pass a string?
I think it would be a problem, but I wouldn't consider this as a blocker for this specific issue, ie. every time we accept a date we should also accept a (properly formatted) string

Answering both comments here:

My train of thought is that implicit casting works for other functions too, and those functions don't accept keywords (for dates, I mean). I tested Kibana with DATE_DIFF("day", "2020-10-10", 1::date), and it works correctly.

While testing this, however, I just found that we only implicit-cast literals, so this fails in both Kibana and esql, and would fail also in TRANGE after this change: DATE_DIFF("day", "2020-10-10", 1::string)

So, quite a shame, but I'll revert this change, and apply the timezone to the custom string conversion, as removing this now is a breaking change. I'll track it in a different issue, as I think it's worth doing for standardization

Restored the keyword handling in this PR, and created an issue here: #140386
Also, added the tests for the edge case that would be breaking, so we don't forget it

…rsing and tests

leontyevdv

LGTM. Thanks Iván!

# Conflicts: # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

…i-project-tests * upstream/main: (23 commits) Fix `testAckListenerReceivesNacksIfPublicationTimesOut` (elastic#140514) Reduce priority of clear-cache tasks (elastic#139685) Add docs and tests about `StreamOutput` to memory (elastic#140365) ES|QL - dense_vector support for COUNT, PRESENT, ABSENT aggregator functions (elastic#139914) Add release notes for v9.2.4 release (elastic#140487) Add release notes for v9.1.10 release (elastic#140488) Add conncectors release notes for 9.1.10, 9.2.4 (elastic#140499) Add parameter support in PromQL query durations (elastic#139873) Improve testing of STS credentials reloading (elastic#140114) Fix zstd native binary publishing script to support newer versions (elastic#140485) Add FlattenedFieldBinaryVsSortedSetDocValuesSyntheticSourceIT (elastic#140489) Store fallback match only text fields in binary doc values (elastic#140189) [DiskBBQ] Use the new merge executor for intra-merge parallelism (elastic#139942) ESQL: introduce support for mapping-unavailable fields (elastic#140463) Add ESNextOSQVectorsScorerTests (elastic#140436) Disable high cardinality tests on release builds (elastic#140503) ESQL: TRange timezone support (elastic#139911) Directly compressing `StreamOutput` (elastic#140502) ES|QL - fix dense vector enrich bug (elastic#139774) Use CrossProjectModeDecider in RemoteClusterService (elastic#140481) ...

- Added timezone support to `TRange(<date_period>)`. Now a `TRange(-1d)` will honor DST - Changed the `Configuration.now` field to be a constructor param. Currently, it was created inside, which made testing harder - Also changed it to be an `Instant` instead of a ZonedDateTime. It was also converted back to an instant, and there's no meaning in a zone here, as it's an absolute point in time. Plus there's a separated "zoneId" field.

ivancea added 8 commits December 19, 2025 17:57

Remove string type from TRange params, delegate on inline casting

3f433f3

Remove unused TRange string conversion

de155a2

Make "now" a configuration param

354b964

Remove keyword tests for TRange, and updated docs

0b6dc21

Merge branch 'main' into esql-trange-timezone

30e7a92

Removei nstant handling from TRange productive code and autogenerate …

53ab7b1

…expected values in tests

Fixed tests and added case fr nanos, in UTC

3c5062b

Added timezone tests and fixed tests

74a6692

ivancea added >feature Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) :Analytics/ES|QL AKA ESQL v9.4.0 labels Dec 22, 2025

Update docs/changelog/139911.yaml

e297331

ivancea commented Dec 22, 2025

View reviewed changes

ivancea requested review from bpintea, leontyevdv and luigidellaquila December 22, 2025 18:00

ivancea and others added 4 commits December 23, 2025 11:39

Merge branch 'main' into esql-trange-timezone

05ecf56

Fix checkstyle removing wildcard imports

243c647

Fixed TRange error tests

79c449d

Merge branch 'main' into esql-trange-timezone

6903079

hawkhuang-collab assigned ivancea Dec 30, 2025

luigidellaquila approved these changes Jan 8, 2026

View reviewed changes

ivancea added 3 commits January 8, 2026 13:09

Merge branch 'main' into esql-trange-timezone

471b21c

Restored keyword input parameters on TRange, and added timezone to pa…

8d5c27f

…rsing and tests

Restore VerifierTests

90a0892

leontyevdv approved these changes Jan 12, 2026

View reviewed changes

Merge branch 'main' into esql-trange-timezone

e142687

# Conflicts: # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

ivancea merged commit ccf8c3c into elastic:main Jan 12, 2026
35 checks passed

ivancea deleted the esql-trange-timezone branch January 12, 2026 14:35

Conversation

ivancea commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticsearchmachine commented Dec 22, 2025

Uh oh!

elasticsearchmachine commented Dec 22, 2025

Uh oh!

github-actions bot commented Dec 22, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ivancea commented Dec 22, 2025

Uh oh!

luigidellaquila left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

luigidellaquila Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leontyevdv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ivancea commented Dec 22, 2025 •

edited

Loading

luigidellaquila Jan 8, 2026 •

edited

Loading