kosiew commented on code in PR #26041:
URL: https://github.com/apache/datafusion/pull/26041#discussion_r4346760754
##########
docs/source/user-guide/sql/scalar_functions.md:
##########
@@ -2472,6 +2472,8 @@ Calculates time intervals and returns the start of the
interval nearest to the s
For example, if you "bin" or "window" data into 15 minute intervals, an input
timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15
minute bin it is in: `2023-01-01T18:15:00Z`.
+Bins are anchored to an origin instant (the UNIX epoch by default); an origin
does not adjust for daylight saving time. For example, a bin aligned to
midnight in `America/Denver` can shift to 01:00 after the spring daylight
saving transition. Use `date_trunc` for calendar units such as local days. To
bin other intervals on local wall-clock boundaries, convert the timestamp with
`to_local_time(expression AT TIME ZONE '<zone>')` before calling `date_bin`,
then apply `AT TIME ZONE` to the result if a timezone-aware timestamp is needed.
Review Comment:
Consider specifying a `1 day` stride in the Denver example. The
midnight-to-01:00 shift illustrates fixed 24-hour bins, whereas hourly bins
remain aligned to local hour boundaries across Denver's one-hour DST change.
For clarity, perhaps say "a daily bin anchored to local midnight before the
spring transition." Please update the source documentation as well and
regenerate the reference if you make this change.
##########
datafusion/functions/src/datetime/date_bin.rs:
##########
@@ -53,6 +53,8 @@ use chrono::{DateTime, Datelike, Duration, Months, TimeDelta,
Utc};
Calculates time intervals and returns the start of the interval nearest to the
specified timestamp. Use `date_bin` to downsample time series data by grouping
rows into time-based "bins" or "windows" and applying an aggregate or selector
function to each window.
For example, if you "bin" or "window" data into 15 minute intervals, an input
timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15
minute bin it is in: `2023-01-01T18:15:00Z`.
+
+Bins are anchored to an origin instant (the UNIX epoch by default); an origin
does not adjust for daylight saving time. For example, a bin aligned to
midnight in `America/Denver` can shift to 01:00 after the spring daylight
saving transition. Use `date_trunc` for calendar units such as local days. To
bin other intervals on local wall-clock boundaries, convert the timestamp with
`to_local_time(expression AT TIME ZONE '<zone>')` before calling `date_bin`,
then apply `AT TIME ZONE` to the result if a timezone-aware timestamp is needed.
Review Comment:
As an optional follow-up, consider adding a before/after-DST comparison to
`datafusion/sqllogictest/test_files/datetime/timestamps.slt`. With origin
`2024-01-01T00:00:00-07:00`, daily instant bins for Denver local noon on March
9 and March 11 start at `00:00-07:00` and `01:00-06:00`, while
`date_trunc('day', ...)` and wall-clock binning with timezone reattachment
should preserve local midnight. The existing tests at lines 4536–4545 already
cover the conversion recipe, so the value would be explicitly testing the DST
contrast. This is not required for this documentation-only PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
