diff --git a/presto-docs/src/main/sphinx/language.rst b/presto-docs/src/main/sphinx/language.rst index a19e4b60733b..cad3232778ee 100644 --- a/presto-docs/src/main/sphinx/language.rst +++ b/presto-docs/src/main/sphinx/language.rst @@ -7,3 +7,4 @@ SQL Language language/types language/reserved + language/timestamp diff --git a/presto-docs/src/main/sphinx/language/timestamp.rst b/presto-docs/src/main/sphinx/language/timestamp.rst new file mode 100644 index 000000000000..810d53d6da63 --- /dev/null +++ b/presto-docs/src/main/sphinx/language/timestamp.rst @@ -0,0 +1,60 @@ +======================== +Legacy And New Timestamp +======================== + +New ``TIMESTAMP`` and ``TIME`` semantics align the types with the SQL standard. +See the following sections for details. + +.. note:: + + The new ``TIMESTAMP`` semantics is still experimental. It's recommended to keep + the legacy ``TIMESTAMP`` semantics enabled. You can experiment with the new semantics + by configuring it globally or on a per-session basis. The legacy semantics + may be deprecated in a future release. + +Configuration +------------- + +The legacy semantics can be enabled using the ``deprecated.legacy-timestamp`` +config property. Setting it to ``true`` (the default) enables the legacy semantics, +whereas setting it to ``false`` enables the new semantics. + +Additionally, it can be enabled or disabled on a per-session basis +with the ``legacy_timestamp`` session property. + +TIMESTAMP semantic changes +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, the ``TIMESTAMP`` type described an instance in time in the Presto session's time zone. +Now, Presto treats ``TIMESTAMP`` values as a set of the following fields representing wall time: + + * ``YEAR OF ERA`` + * ``MONTH OF YEAR`` + * ``DAY OF MONTH`` + * ``HOUR OF DAY`` + * ``MINUTE OF HOUR`` + * ``SECOND OF MINUTE`` - as ``DECIMAL(5, 3)`` + +For that reason, a ``TIMESTAMP`` value is not linked with the session time zone in any way until +a time zone is needed explicitly, such as when casting to a ``TIMESTAMP WITH TIME ZONE`` or +``TIME WITH TIME ZONE``. In those cases, the time zone offset of the session time zone is applied, +as specified in the SQL standard. + +TIME semantic changes +~~~~~~~~~~~~~~~~~~~~~ + +The ``TIME`` type was changed similarly to the ``TIMESTAMP`` type. + +TIME WITH TIME ZONE semantic changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to compatibility requirements, having ``TIME WITH TIME ZONE`` completely aligned with the SQL +standard was not possible yet. For that reason, when calculating the time zone offset for ``TIME WITH +TIME ZONE``, Presto uses the session's start date and time. + +This can be seen in queries using ``TIME WITH TIME ZONE`` in a time zone that has had time zone policy +changes or uses DST. For example, with a session start time of 2017-03-01: + + * Query: ``SELECT TIME '10:00:00 Asia/Kathmandu' AT TIME ZONE 'UTC'`` + * Legacy result: ``04:30:00.000 UTC`` + * New result: ``04:15:00.000 UTC`` diff --git a/presto-docs/src/main/sphinx/language/types.rst b/presto-docs/src/main/sphinx/language/types.rst index 039f60dcec02..9dbc38e1deb4 100644 --- a/presto-docs/src/main/sphinx/language/types.rst +++ b/presto-docs/src/main/sphinx/language/types.rst @@ -133,6 +133,8 @@ String Date and Time ------------- +See also :doc:`/language/timestamp` + ``DATE`` ^^^^^^^^