Skip to content

Commit 4a6d155

Browse files
adriangbclaude
andcommitted
docs: say timestamptz drops the zone metadata, not the offset
The input offset still sets the instant. Also list TIMESTAMP(p) WITHOUT TIME ZONE and fix the INTERVAL type name. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent fe3bb49 commit 4a6d155

1 file changed

Lines changed: 13 additions & 8 deletions

File tree

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

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -105,20 +105,25 @@ 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(p)`, `TIMESTAMP WITHOUT TIME ZONE` | `Timestamp(unit, None)` |
113-
| `TIMESTAMPTZ(p)`, `TIMESTAMP(p) WITH TIME ZONE` | `Timestamp(unit, None)` by default — see the warning below |
114-
| `INTERVAL` | `Interval(IntervalMonthDayNano)` |
108+
| SQL DataType | Arrow DataType |
109+
| ------------------------------------------------------------- | :--------------------------------------------------------- |
110+
| `DATE` | `Date32` |
111+
| `TIME` | `Time64(Nanosecond)` |
112+
| `TIMESTAMP`, `TIMESTAMP(p)`, `TIMESTAMP(p) WITHOUT TIME ZONE` | `Timestamp(unit, None)` |
113+
| `TIMESTAMPTZ(p)`, `TIMESTAMP(p) WITH TIME ZONE` | `Timestamp(unit, None)` by default — see the warning below |
114+
| `INTERVAL` | `Interval(MonthDayNano)` |
115115

116116
:::{warning}
117117
`TIMESTAMPTZ` and `TIMESTAMP WITH TIME ZONE` do **not** give a timezone-aware
118118
type by default. The zone comes from the
119119
[`datafusion.execution.time_zone`] setting, and that setting is unset unless you
120120
set it. So `'2024-01-01T12:00:00Z'::timestamptz` gives `Timestamp(unit, None)`
121-
by default, and DataFusion discards the `Z`.
121+
by default: the result type does not keep timezone metadata.
122+
123+
An explicit offset in the input is still applied. DataFusion normalizes the
124+
value to UTC. For example, with the default setting,
125+
`'2024-01-01T12:00:00+07:00'::timestamptz` gives `2024-01-01T05:00:00`. It is
126+
not read as the local time `12:00:00`.
122127

123128
This is a known bug. See [issue #25166]. PostgreSQL and DuckDB always give an
124129
aware type here, because their session time zone always has a value.

0 commit comments

Comments
 (0)