fix: time ± interval returns a wrapped time instead of an interval

[vismaytiwari]

Which issue does this PR close?

• Closes PostgreSQL compatibility: time + interval should wrap within the 24-hour time domain #22265
• Closes PostgreSQL compatibility: time - interval should wrap within the 24-hour time domain #22255

Rationale for this change

time + interval (and interval + time / time - interval) returned an Interval instead of a time, so the value was never wrapped within the 24-hour clock:

> SELECT time '23:30' + interval '2 hours';
25 hours 30 mins   -- an Interval, not a time

PostgreSQL (and DuckDB) return a time that wraps around midnight:

01:30:00

The root cause is in type coercion: time <op> interval was coerced by widening the time operand into an Interval, so the addition happened between two intervals and the result kept the Interval type.

What changes are included in this PR?

Following the existing Date - Date special case (in the same two files), time ± interval is now handled explicitly:

• Coercion (expr-common/src/type_coercion/binary.rs): time + interval, interval + time, and time - interval now coerce to (time, interval) — the interval normalized to MonthDayNano, and the time operand kept at its own unit, which is also the result type. interval - time, which is not meaningful, is left unchanged.
• Evaluation (physical-expr/src/expressions/binary.rs): a new apply_time_interval adds/subtracts the interval's sub-day component and wraps the result modulo 24 hours, for all four time units (Time32(Second|Millisecond), Time64(Microsecond|Nanosecond)) and both operand orders. The result keeps the input time's unit, mirroring timestamp/date + interval (which preserve their unit and apply the interval at that resolution); interval precision finer than the time's unit is truncated, so time(s) + interval '1 nanosecond' is a no-op, exactly like timestamp(s) + interval '1 nanosecond'. Only the interval's sub-day portion affects a time-of-day; whole months and days are ignored, matching PostgreSQL (e.g. time '10:00' + interval '1 day 2 hours' = 12:00:00).

time - time (→ Interval) is unchanged.

Are these changes tested?

Yes. datafusion/sqllogictest/test_files/datetime/arith_time_interval.slt was previously a characterization test that documented the incorrect Interval output; it now asserts the correct wrapped time results — including wrapping past midnight in both directions (22:00 + 3h → 01:00:00, 02:00 - 3h → 23:00:00), ignoring whole days, preserving each input time unit (arrow_typeof per unit), and the finer-than-unit interval truncation.

Are there any user-facing changes?

Yes — time ± interval now returns a time value (wrapped within 24 hours) instead of an Interval, aligning DataFusion with PostgreSQL and DuckDB. The result keeps the input time's unit rather than widening it (see the 55.0.0 upgrade guide).

[vismaytiwari]

Fixed the rustfmt failure from the first run — fmt, the unit tests, and the datetime sqllogictests all pass locally. The workflows just need approval to run on the updated commit.

[Jefffrey]

it makes sense to make this change to me, given two other systems behave similarly and having time + interval = interval seems non-obvious (our current behaviour)

we'll need a note in the upgrade guide since this is a user facing change

[Jefffrey]

similarly here i feel we can avoid this cast

[vismaytiwari]

Agreed. I moved the normalization up into the coercion layer, so the time operand now arrives as Time64(Nanosecond) and there's no cast here anymore. That does make the result Time64(Nanosecond) regardless of the input time unit — I called that out in the upgrade guide.

[Jefffrey]

my main concern now is that we always cast the time to time(ns) when adding an interval. i was hoping we could try preserve the time unit, but thinking on it more we run into edge cases like when if time(s) + interval '1 nanosecond' 🤔

im not sure looking to other systems can help us here since i dont think they have different granularities for their time types like we do here

[vismaytiwari]

@Jefffrey yeah, I don't think other systems help here — but we've actually got the precedent in-tree. get_result hands timestamp/date + interval straight to arrow's add_wrapping, and arrow keeps the input unit: timestamp(s) + interval '1 nanosecond' already comes back as timestamp(s) with the sub-second part truncated. So the edge case you're worried about isn't new — it's exactly what timestamps do today.

That gives us a consistent option: preserve the time unit and apply the interval at that resolution, so time(s) + interval '1 nanosecond' → time(s) unchanged, same as the timestamp case. The only cost is that silent truncation for the coarse time types. The current PR goes the other way (always widen to time(ns)), which keeps the precision but changes the column type.

I lean toward preserving the unit — it matches timestamp/date arithmetic and keeps a time(s) column time(s). It's contained: keep the time type in the coercion instead of forcing Time64(ns), and branch apply_time_interval per unit (right now everything funnels through one ns wrap). Want me to go that way?

[Jefffrey]

thanks for double checking; if we do that for timestamps then it makes sense to do for time as well 👍

[vismaytiwari]

Done — pushed. The result now keeps the input time's unit instead of widening to Time64(ns): the coercion arm carries the time operand's type through as the result type, and apply_time_interval dispatches per unit (a small generic wrap_time_interval<T>) so the interval is applied at the time's resolution. Finer-than-unit precision truncates, so time(s) + interval '1 nanosecond' is a no-op — same as timestamp(s) + interval '1 nanosecond'.

Added per-unit arrow_typeof assertions and the truncation cases to the slt; cargo test (coercion + physical-expr), the datetime slt, fmt and clippy --all-targets -D warnings are all green locally. Also refreshed the 55.0.0 upgrade note (it had said the result was always ns).

[codecov-commenter]

Codecov Report

❌ Patch coverage is 79.82456% with 23 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@95de385). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
datafusion/physical-expr/src/expressions/binary.rs	76.84%	19 Missing and 3 partials ⚠️
datafusion/expr-common/src/type_coercion/binary.rs	94.73%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #23279   +/-   ##
=======================================
  Coverage        ?   80.65%           
=======================================
  Files           ?     1086           
  Lines           ?   366212           
  Branches        ?   366212           
=======================================
  Hits            ?   295359           
  Misses          ?    53256           
  Partials        ?    17597           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Jefffrey]

something to consider is how subtraction affects this. see (checked out on this branch):

> select arrow_cast('2026-07-17T10:00:00', 'Timestamp(s)') - interval '1 nanosecond';
+----------------------------------------------------------------------------------------------------------------------------------------------------+
| arrow_cast(Utf8("2026-07-17T10:00:00"),Utf8("Timestamp(s)")) - IntervalMonthDayNano("IntervalMonthDayNano { months: 0, days: 0, nanoseconds: 1 }") |
+----------------------------------------------------------------------------------------------------------------------------------------------------+
| 2026-07-17T09:59:59                                                                                                                                |
+----------------------------------------------------------------------------------------------------------------------------------------------------+
1 row(s) fetched.
Elapsed 0.005 seconds.

> select arrow_cast('10:00:00', 'Time32(s)') - interval '1 nanosecond';
+--------------------------------------------------------------------------------------------------------------------------------------+
| arrow_cast(Utf8("10:00:00"),Utf8("Time32(s)")) - IntervalMonthDayNano("IntervalMonthDayNano { months: 0, days: 0, nanoseconds: 1 }") |
+--------------------------------------------------------------------------------------------------------------------------------------+
| 10:00:00                                                                                                                             |
+--------------------------------------------------------------------------------------------------------------------------------------+
1 row(s) fetched.
Elapsed 0.007 seconds.

[vismaytiwari]

my truncation-toward-zero disagreed with timestamp here. Switched to flooring the interval at ns precision (div_euclid, with the sign applied before the floor), so time(s) - interval '1 nanosecond' now rolls back a full second to 09:59:59, matching your timestamp(s) example. Added an slt case for it. a968da4

[Jefffrey]

should be good once conflicts are resolved and CI is green

[vismaytiwari]

Thanks @Jefffrey! Rebased on main and resolved the 55.0.0.md conflict — it was just an upgrade-note section colliding at the tail of the file each time, nothing in the code. The workflow runs are sitting in "action required" (fork PR), so they need a maintainer to kick them off whenever you get a sec. Green locally: the datetime/arith_time_interval slt, cargo fmt, and clippy --all-targets --all-features -- -D warnings all pass.