Skip to content

Update documentation for parametric TIME WITH TIME ZONE #5316 #7912

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
electrum merged 5 commits into from
Jun 4, 2021
Merged

Update documentation for parametric TIME WITH TIME ZONE #5316 #7912

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b04ca94
Update types.rst
meggpie May 13, 2021
79c1362
Update types.rst
meggpie May 17, 2021
b7cd8ac
Update types.rst
meggpie May 28, 2021
44c28fd
Update types.rst
electrum Jun 4, 2021
04ffa63
Update types.rst
electrum Jun 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/src/main/sphinx/language/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,8 +168,10 @@ Example: ``TIME '01:02:03.456'``

Time of day (hour, minute, second, millisecond) with a time zone.
Values of this type are rendered using the time zone from the value.
Time zones are expressed as the numeric UTC offset value::

Example: ``TIME '01:02:03.456 America/Los_Angeles'``
SELECT TIME '01:02:03.456 -08:00';
-- 1:02:03.456-08:00

.. _timestamp-data-type:

Expand Down Expand Up @@ -227,8 +229,11 @@ The following examples illustrate the behavior::
Instant in time that includes the date and time of day with ``P`` digits of
precision for the fraction of seconds and with a time zone. Values of this
type are rendered using the time zone from the value.
Time zones are expressed as the numeric UTC offset value::
Copy link
Copy Markdown
Member

@findepi findepi Aug 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This turned out to be understood as indicating that Trino supports numeric offset zones, but not named zones.
see trinodb/trino-python-client#229 (comment) cc @jhlodin

we need to improve the wording to clarify named zones are supported

cc @mosabua

Copy link
Copy Markdown
Member

@hashhar hashhar Aug 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably we need to mention this separately both TIME and TIMESTAMPTZ since TIME doesn't support named zones (since they don't make sense there) while TIMESTAMPTZ does.

Copy link
Copy Markdown
Member

@mosabua mosabua Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whatever supports timezone should be consistent .. is that the case now.. I am not sure to be honest.

Copy link
Copy Markdown
Member

@hashhar hashhar Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It cannot be consistent since TIME has no concept of named zones. What does TIME '01:01:01' America/Los_Angeles mean? Depending on what day it was America/Los_Angeles can mean different things.

We need to explicitly make it more clear that TIME with timezone supports only offsets and not named zones while TIMESTAMP with timezone supports both named offsets and numbered offsets.

Copy link
Copy Markdown
Member

@findepi findepi Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does TIME '01:01:01' America/Los_Angeles mean?

This is a wrong question to ask. We don't need to go into details why.

TIME has no concept of named zones.

yes, it does not.

Copy link
Copy Markdown
Member

@martint martint Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

time(p) with time zone is in the SQL standard. It's defined as a time with a time zone displacement containing an hour and a minute component in the range -14:00 to +14:00. That's the only concept of timezones supported by the specification, even for the timestamp(p) with time zone type. Support for political time zones is an extension to the standard.

Copy link
Copy Markdown
Member

@mosabua mosabua Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So .. to simplify for users and consistency .. should we remove the support for political time zones everywhere?

Copy link
Copy Markdown
Member

@martint martint Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, political timezones are useful and necessary for timestamp(p) with time zone.

Copy link
Copy Markdown
Member

@mosabua mosabua Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay ... I think we have enough info now to run with a doc update PR .. @jhlodin will submit soon.

Copy link
Copy Markdown
Contributor

@jhlodin jhlodin Aug 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proposed type docs change here: #13927


TIMESTAMP '2001-08-22 03:04:05.321 -08:00';
-- 2001-08-22 03:04:05.321-08:00

Example: ``TIMESTAMP '2001-08-22 03:04:05.321 America/Los_Angeles'``

``INTERVAL YEAR TO MONTH``
^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down