perf: Optimize date_part for timestamp values without timezones

[neilconway]

Which issue does this PR close?

• N/A

Rationale for this change

For timestamp inputs, date_part generally converts the timestamp to a Chrono value and then uses Chrono to extract the requested component. For timestamps without a timezone, hour through nanosecond components can be calculated directly from the stored integer, without determining the calendar date. This is roughly 5-20x faster than going through Chrono on a microbenchmark (results below).

This is partly motivated by improving the performance of date_part and extract in DataFusion. For example, ClickBench Q18 improves by about 2% using this optimization.

Benchmarks: (ARM64, elapsed times in microseconds)

• timestamp_s/Hour/no_nulls: 33.366 → 5.827, −82.5%
• timestamp_s/Minute/no_nulls: 36.901 → 7.108, −80.7%
• timestamp_s/Second/no_nulls: 35.321 → 2.530, −92.8%
• timestamp_s/Hour/mixed_nulls: 30.885 → 5.821, −81.2%
• timestamp_s/Year/control: 32.893 → 32.913, +0.1%
• timestamp_s/Minute/timezone_control: 59.305 → 59.081, −0.4%
• timestamp_s/Second/timezone_control: 55.782 → 56.263, +0.9%
• timestamp_ms/Hour/no_nulls: 45.351 → 5.839, −87.1%
• timestamp_ms/Minute/no_nulls: 49.214 → 6.235, −87.3%
• timestamp_ms/Second/no_nulls: 47.252 → 6.226, −86.8%
• timestamp_ms/Millisecond/no_nulls: 44.510 → 2.317, −94.8%
• timestamp_ms/Microsecond/no_nulls: 44.503 → 2.472, −94.4%
• timestamp_ms/Nanosecond/no_nulls: 43.116 → 2.375, −94.5%
• timestamp_ms/Hour/mixed_nulls: 39.190 → 5.859, −85.1%
• timestamp_ms/Year/control: 44.099 → 44.754, +1.5%
• timestamp_ms/Minute/timezone_control: 73.426 → 73.751, +0.4%
• timestamp_ms/Nanosecond/timezone_control: 65.517 → 65.771, +0.4%
• timestamp_us/Hour/no_nulls: 41.028 → 6.520, −84.1%
• timestamp_us/Minute/no_nulls: 44.774 → 6.777, −84.9%
• timestamp_us/Second/no_nulls: 42.947 → 6.238, −85.5%
• timestamp_us/Millisecond/no_nulls: 40.022 → 2.629, −93.4%
• timestamp_us/Microsecond/no_nulls: 39.975 → 2.304, −94.2%
• timestamp_us/Nanosecond/no_nulls: 39.116 → 2.365, −94.0%
• timestamp_us/Hour/mixed_nulls: 39.438 → 6.486, −83.6%
• timestamp_us/Year/control: 39.921 → 40.406, +1.2%
• timestamp_us/Minute/timezone_control: 68.042 → 68.354, +0.5%
• timestamp_us/Nanosecond/timezone_control: 61.106 → 61.602, +0.8%
• timestamp_ns/Hour/no_nulls: 40.454 → 3.540, −91.2%
• timestamp_ns/Minute/no_nulls: 44.499 → 3.388, −92.4%
• timestamp_ns/Second/no_nulls: 42.425 → 6.241, −85.3%
• timestamp_ns/Millisecond/no_nulls: 39.546 → 2.628, −93.4%
• timestamp_ns/Microsecond/no_nulls: 39.388 → 2.627, −93.3%
• timestamp_ns/Nanosecond/no_nulls: 38.727 → 2.304, −94.1%
• timestamp_ns/Hour/mixed_nulls: 38.805 → 3.542, −90.9%
• timestamp_ns/Year/control: 39.567 → 39.710, +0.4%
• timestamp_ns/Minute/timezone_control: 69.019 → 68.191, −1.2%
• timestamp_ns/Nanosecond/timezone_control: 61.682 → 61.172, −0.8%

What changes are included in this PR?

• Optimize date_part as described above
• Add unit tests
• Add benchmark

Are these changes tested?

Existing tests pass. Two new tests were added: one checks the consistency of this code path with the results produced by Chrono; the second checks the results of this code path for extreme values (outside of Chrono's supported calendar range).

Are there any user-facing changes?

There is one user-visible behavior change. Chrono has a limited calendar range (roughly +/- 262,000 years); calling date_part on timestamps outside that range returned null. This implementation is defined for the entire range of timestamp values. The returned value is correct, but this behavior is slightly inconsistent with date_part for units that are still implemented via Chrono, and for timestamp values with time zones.

AI usage

Developed with Codex Astra 6, reviewed with Claude Code Fable 5.1. I then reviewed and revised the resulting code.

[mbutrovich]

Thanks @neilconway, this is a nice speedup and the tests against Chrono are thorough.

[mbutrovich]

Thanks for calling this out. I'm not sure which behavior is better here, and I'd be interested in what you and the other maintainers think. With this PR, one out-of-range row in a TimestampSecond array returns Hour = 15 and Year = NULL. The same value with a timezone returns NULL for both, and casting it to Time64 returns an error (as_time_res_with_timezone, used by the Timestamp to Time64 cast).

If we'd like to keep the current semantics, one option is to check the range before taking the fast path. For TimestampNanosecond every i64 is in Chrono's range, so it needs no check. For the other units, one branch-free pass over values() against the DateTime::<Utc>::MIN_UTC and MAX_UTC bounds would work, with a fallback to the existing path when a value is out of range. This is the check I tried, at the top of timestamp_time_part:

if !matches!(
    part,
    DatePart::Hour
        | DatePart::Minute
        | DatePart::Second
        | DatePart::Millisecond
        | DatePart::Microsecond
        | DatePart::Nanosecond
) {
    return None;
}
if T::UNIT != TimeUnit::Nanosecond {
    let (min, max) = (DateTime::<Utc>::MIN_UTC, DateTime::<Utc>::MAX_UTC);
    let (lo, hi) = match T::UNIT {
        TimeUnit::Second => (min.timestamp(), max.timestamp()),
        TimeUnit::Millisecond => (min.timestamp_millis(), max.timestamp_millis()),
        _ => (min.timestamp_micros(), max.timestamp_micros()),
    };
    if !array.values().iter().fold(true, |ok, &v| ok & (lo <= v) & (v <= hi)) {
        return None;
    }
}

The early matches! keeps Year and the other calendar parts from paying for the scan. With this in place, test_timestamp_time_parts_extremes would expect NULL for the out-of-range values.

When I tried this with your bench on an M5 Max, it added about 0.7 us per 8192 values. For example, ms Hour went from 5.37 to 6.08 us and ms Millisecond from 2.12 to 2.87 us, against about 43 us on the Chrono path. That seems like a reasonable cost to me, but you may see a better way to do it. If we keep the new behavior instead, the api-change label would make sure it shows up in the changelog.

[neilconway]

My two cents: the current behavior implemented by the PR is the better option. The historical behavior of date_part is an unfortunate implementation detail from using Chrono; defining date_part for a wider range is values is not inherently bad (it's good, actually!), and it is also considerably faster.

The main downside is inconsistency between extracting different time components for timestamps with extreme values. That's a bit odd but it doesn't seem like a showstopper to me. The current behavior for out-of-range timestamps is arguably a defect to begin with -- e.g., in the future we could perhaps improve date_part so that it is defined for all timestamps and all time components.

[mbutrovich]

Sounds good as long as it's documented for users.

[neilconway]

Cool. The current PR has documentation that seems sufficient to me, but lmk if you have suggestions for other places to document this.

[neilconway]

Thanks for the review, @mbutrovich !

[mbutrovich]

Thanks @neilconway for adding the timezone cases and refreshing the numbers. The bench now matches the description.

[mbutrovich]

Thanks @neilconway, LGTM!

[neilconway]

@alamb Can you take a look, if you get a chance? This has already been approved by Matt.

[Jefffrey]

thanks @neilconway & @mbutrovich