Skip to content

Add utc_tz_aware="schema" mode for schema-matching datetime output#653

Merged
joe-clickhouse merged 4 commits intomainfrom
joe/645-add-explicit-timezone-mode-for-schema-matching-datetime-output
Feb 19, 2026
Merged

Add utc_tz_aware="schema" mode for schema-matching datetime output#653
joe-clickhouse merged 4 commits intomainfrom
joe/645-add-explicit-timezone-mode-for-schema-matching-datetime-output

Conversation

@joe-clickhouse
Copy link
Contributor

@joe-clickhouse joe-clickhouse commented Feb 18, 2026

Summary

  • Adds utc_tz_aware="schema" mode which returns datetimes that match the server's explicit column definition. That means it'll be timezone-aware when the column schema defines a timezone e.g. DateTime('UTC') and naive for bare DateTime columns
  • Validates the utc_tz_aware parameter and raises ProgrammingError for unrecognized string values
  • Logs a warning when "schema" mode is used with Arrow-based query methods as they don't yet support this mode since ClickHouse attaches the server timezone to all columns in Arrow format

Note on naming

Extending utc_tz_aware from a boolean to also accept a string is admittedly not the cleanest API. The parameter name implies UTC-specific behavior, but "schema" mode applies to all timezones. This is intentional as a short-term unblock for users who need schema-matching behavior now. I'll open a separate issue to rename utc_tz_aware to something more appropriate like tz_mode as part of the 1.0 release which will be happening soon.

Closes #645

Checklist

Delete items not relevant to your PR:

  • Unit and integration tests covering the common scenarios were added
  • A human-readable description of the changes was provided to include in CHANGELOG

Copy link

@mitchhollander mitchhollander left a comment

Choose a reason for hiding this comment

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

Commented with a take it or leave it suggestion.

@joe-clickhouse
Copy link
Contributor Author

joe-clickhouse commented Feb 18, 2026

Just to follow up here, I've pushed a commit to make these changes. You can see them on the branch itself, but for some reason GitHub hasn't propagated to here yet. I'll let this sit for a bit and see if it eventually resolves.

EDIT: pushed empty commit to trigger PR sync and it worked.

…a-matching-datetime-output

Signed-off-by: Joe Spadola <joe.spadola@clickhouse.com>
@joe-clickhouse joe-clickhouse merged commit 2444667 into main Feb 19, 2026
34 checks passed
@joe-clickhouse joe-clickhouse deleted the joe/645-add-explicit-timezone-mode-for-schema-matching-datetime-output branch February 19, 2026 20:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add explicit timezone mode for schema-matching datetime output

2 participants

Comments