Apache DataFusion SQL Query Engine
docs: document the `TIMESTAMP WITH TIME ZONE` type mapping and fix a stale comment (#25171)
Adrian Garcia Badaraccoaece5fb6a32d
diff --git a/datafusion/sql/src/planner.rs b/datafusion/sql/src/planner.rsindex e3f51cb075..d7a1aaf299 100644--- a/datafusion/sql/src/planner.rs+++ b/datafusion/sql/src/planner.rs@@ -775,7 +775,13 @@ impl<'a, S: ContextProvider> SqlToRel<'a, S> {{// Timestamp With Time Zone// INPUT : [SQLDataType] TimestampTz + [Config] Time Zone- // OUTPUT: [ArrowDataType] Timestamp<TimeUnit, Some(Time Zone)>+ // OUTPUT: [ArrowDataType] Timestamp<TimeUnit, Time Zone>+ //+ // Note that the configured time zone is an `Option` that is+ // unset by default, so by default this yields the+ // timezone-naive `Timestamp<TimeUnit, None>`. Whether that+ // should remain the behavior is tracked in+ // https://github.com/apache/datafusion/issues/25166self.context_provider.options().execution.time_zone.clone()} else {// Timestamp Without Time zonediff --git a/docs/source/user-guide/sql/data_types.md b/docs/source/user-guide/sql/data_types.mdindex 2e75fce6c7..39442d38c4 100644--- a/docs/source/user-guide/sql/data_types.md+++ b/docs/source/user-guide/sql/data_types.md@@ -105,12 +105,42 @@ The maximum supported precision for `DECIMAL` types is 76.## Date/Time Types-| SQL DataType | Arrow DataType |-| ------------ | :------------------------------- |-| `DATE` | `Date32` |-| `TIME` | `Time64(Nanosecond)` |-| `TIMESTAMP` | `Timestamp(Nanosecond, None)` |-| `INTERVAL` | `Interval(IntervalMonthDayNano)` |+| SQL DataType | Arrow DataType |+| ------------------------------------------------------------- | :--------------------------------------------------------- |+| `DATE` | `Date32` |+| `TIME` | `Time64(Nanosecond)` |+| `TIMESTAMP`, `TIMESTAMP(p)`, `TIMESTAMP(p) WITHOUT TIME ZONE` | `Timestamp(unit, None)` |+| `TIMESTAMPTZ(p)`, `TIMESTAMP(p) WITH TIME ZONE` | `Timestamp(unit, None)` by default — see the warning below |+| `INTERVAL` | `Interval(MonthDayNano)` |++:::{warning}+`TIMESTAMPTZ` and `TIMESTAMP WITH TIME ZONE` do **not** give a timezone-aware+type by default. The zone comes from the+[`datafusion.execution.time_zone`] setting, and that setting is unset unless you+set it. So `'2024-01-01T12:00:00Z'::timestamptz` gives `Timestamp(unit, None)`+by default: the result type does not keep timezone metadata.++An explicit offset in the input is still applied. DataFusion normalizes the+value to UTC. For example, with the default setting,+`'2024-01-01T12:00:00+07:00'::timestamptz` gives `2024-01-01T05:00:00`. It is+not read as the local time `12:00:00`.++This is a known bug. See [issue #25166]. PostgreSQL and DuckDB always give an+aware type here, because their session time zone always has a value.++Set `datafusion.execution.time_zone` to make these types aware. `'UTC'` is a+good value.+:::++`unit` comes from the optional precision `p` on the two `TIMESTAMP` rows. Use+`0`, `3`, `6` or `9` for `Second`, `Millisecond`, `Microsecond` or `Nanosecond`.+DataFusion rejects each other value of `p`. If you omit `p`, the unit is+`Nanosecond`. The precision goes after `TIMESTAMPTZ`, but before+`WITH TIME ZONE`: use `TIMESTAMPTZ(3)` or `TIMESTAMP(3) WITH TIME ZONE`.+`DATE`, `TIME` and `INTERVAL` do not accept a precision.++[`datafusion.execution.time_zone`]: ../configs.md+[issue #25166]: https://github.com/apache/datafusion/issues/25166## Boolean Types