Skip to content

Commit e93196a

Browse files
adriangbclaude
andcommitted
docs: fix stale TIMESTAMP WITH TIME ZONE comment, document the mapping
The comment on the `SQLDataType::Timestamp` arm in `planner.rs` promises `Timestamp<TimeUnit, Some(Time Zone)>`, but the expression it describes is an `Option<String>` that is `None` by default. That comment went stale in apache#18359, which changed `datafusion.execution.time_zone` from `String` to `Option<String>` and dropped the `Some(...)` wrapper without touching the two lines above it. Correct the comment; the behavior itself is under discussion in apache#25166 and is left unchanged. `docs/source/user-guide/sql/data_types.md` had no row for `TIMESTAMP WITH TIME ZONE` / `TIMESTAMPTZ` at all. Add one, along with the optional `(p)` precision that both it and `TIMESTAMP` accept, and note that the timezone component comes from `datafusion.execution.time_zone`, which is unset by default. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent e640ae0 commit e93196a

2 files changed

Lines changed: 27 additions & 7 deletions

File tree

‎datafusion/sql/src/planner.rs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -775,7 +775,13 @@ impl<'a, S: ContextProvider> SqlToRel<'a, S> {
775775
{
776776
// Timestamp With Time Zone
777777
// INPUT : [SQLDataType] TimestampTz + [Config] Time Zone
778-
// OUTPUT: [ArrowDataType] Timestamp<TimeUnit, Some(Time Zone)>
778+
// OUTPUT: [ArrowDataType] Timestamp<TimeUnit, Time Zone>
779+
//
780+
// Note that the configured time zone is an `Option` that is
781+
// unset by default, so by default this yields the
782+
// timezone-naive `Timestamp<TimeUnit, None>`. Whether that
783+
// should remain the behavior is tracked in
784+
// https://github.com/apache/datafusion/issues/25166
779785
self.context_provider.options().execution.time_zone.clone()
780786
} else {
781787
// Timestamp Without Time zone

‎docs/source/user-guide/sql/data_types.md‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -105,12 +105,26 @@ The maximum supported precision for `DECIMAL` types is 76.
105105

106106
## Date/Time Types
107107

108-
| SQL DataType | Arrow DataType |
109-
| ------------ | :------------------------------- |
110-
| `DATE` | `Date32` |
111-
| `TIME` | `Time64(Nanosecond)` |
112-
| `TIMESTAMP` | `Timestamp(Nanosecond, None)` |
113-
| `INTERVAL` | `Interval(IntervalMonthDayNano)` |
108+
| SQL DataType | Arrow DataType |
109+
| ------------------------------------------------------------------ | :------------------------------- |
110+
| `DATE` | `Date32` |
111+
| `TIME` | `Time64(Nanosecond)` |
112+
| `TIMESTAMP` or `TIMESTAMP(p)` | `Timestamp(unit, None)` |
113+
| `TIMESTAMPTZ` or `TIMESTAMP WITH TIME ZONE`, optionally with `(p)` | `Timestamp(unit, tz)` |
114+
| `INTERVAL` | `Interval(IntervalMonthDayNano)` |
115+
116+
`unit` is determined by the optional precision `p`, which must be `0`, `3`, `6`
117+
or `9` for `Second`, `Millisecond`, `Microsecond` or `Nanosecond` respectively.
118+
Any other precision is rejected. When `p` is omitted the unit is `Nanosecond`.
119+
120+
`tz` is the value of the [`datafusion.execution.time_zone`] setting. That
121+
setting is unset by default, so with the default configuration
122+
`TIMESTAMPTZ` and `TIMESTAMP WITH TIME ZONE` map to `Timestamp(unit, None)`,
123+
the same timezone-naive type as `TIMESTAMP`. Whether that should remain the
124+
mapping is an open question tracked in [issue #25166].
125+
126+
[`datafusion.execution.time_zone`]: ../configs.md
127+
[issue #25166]: https://github.com/apache/datafusion/issues/25166
114128

115129
## Boolean Types
116130

0 commit comments

Comments
 (0)