Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions datafusion/functions/src/datetime/date_bin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"#,
syntax_example = "date_bin(interval, expression[, origin_timestamp])",
sql_example = r#"```sql
Expand Down
2 changes: 2 additions & 0 deletions docs/source/user-guide/sql/scalar_functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


```sql
date_bin(interval, expression[, origin_timestamp])
```
Expand Down
Loading