Visitar URL original
docs: document date_bin DST drift with an explicit origin by Inf1mum · Pull Request #27381 · apache/datafusion · GitHub
Skip to content

docs: document date_bin DST drift with an explicit origin - #27381

Open
Inf1mum wants to merge 1 commit into
apache:mainfrom
Inf1mum:docs/25168-date-bin-dst
Open

Inf1mum wants to merge 1 commit into
apache:mainfrom
Inf1mum:docs/25168-date-bin-dst

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 12, 2026

Copy link
Copy Markdown

Which issue does this PR close?

Rationale for this change

An explicit origin_timestamp chosen to align date_bin bins to local midnight works until the timezone's offset changes, then silently shifts the bins by an hour. There is no error and no warning. This is not a bug in DataFusion — PostgreSQL and DuckDB return identical results, because all three bin on the instant measured from a fixed origin — but the pattern looks correct in every test that does not cross a DST transition, so the issue asks for it to be documented.

What changes are included in this PR?

Adds a short note to the date_bin documentation: an explicit origin fixes an instant, not a recurring local time, so bins aligned to local midnight with an origin silently shift by an hour across a daylight saving time transition. It points users at date_trunc for calendar units, and at date_bin(<stride>, to_local_time(t AT TIME ZONE '<zone>')) for strides that are not calendar units.

The note is added to the rustdoc in datafusion/functions/src/datetime/date_bin.rs and mirrored into docs/source/user-guide/sql/scalar_functions.md (which dev/update_function_docs.sh regenerates from the rustdoc).

What is the testing strategy for this PR?

Docs-only change; no code or test behaviour is touched.

  • cargo test -p datafusion-functions --lib — 410 passed, 0 failed.
  • cargo fmt --check on the touched crate.

Are there any user-facing changes?

Documentation only. No behaviour change, no public API change.

@github-actions github-actions Bot added documentation Improvements or additions to documentation functions Changes to functions implementation labels Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation functions Changes to functions implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document that date_bin with an explicit origin drifts an hour across a DST transition

1 participant