kosiew commented on code in PR #25171:
URL: https://github.com/apache/datafusion/pull/25171#discussion_r4082158121
##########
docs/source/user-guide/sql/data_types.md:
##########
@@ -105,12 +105,37 @@ 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 WITHOUT TIME ZONE` |
`Timestamp(unit, None)` |
+| `TIMESTAMPTZ(p)`, `TIMESTAMP(p) WITH TIME ZONE` |
`Timestamp(unit, None)` by default — see the warning below |
+| `INTERVAL` |
`Interval(IntervalMonthDayNano)` |
+
+:::{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, and DataFusion discards the `Z`.
Review Comment:
I think the wording that DataFusion "discards the `Z`" is a bit misleading
here. The input offset still determines the represented instant. For example,
on this head, `TIMESTAMPTZ '2024-01-01T12:00:00+07:00'` displays as
`2024-01-01T05:00:00` when the session timezone is unset.
Could we instead say that the resulting Arrow type does not retain timezone
metadata? It would also be helpful to mention that an explicit input offset is
still applied and normalized, so readers do not come away thinking an
offset-bearing timestamp is interpreted as a local naive timestamp.
##########
docs/source/user-guide/sql/data_types.md:
##########
@@ -105,12 +105,37 @@ 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 WITHOUT TIME ZONE` |
`Timestamp(unit, None)` |
Review Comment:
Small completeness suggestion: could we also list `TIMESTAMP(p) WITHOUT TIME
ZONE` here? It is accepted, for example `CAST('2000-01-01' AS TIMESTAMP(3)
WITHOUT TIME ZONE)` yields `Timestamp(ms)`, and the table is otherwise pretty
thorough about the precision-bearing timestamp forms.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
