Add timezone support to v3 SQL docs #5581

sanderson · 2024-08-28T21:29:31Z

Updates information about time zones in SQL across all v3 products
Updates SQL data types documentation
Adds missing time and date functions
Adds information about how timezones change the behavior of some functions.

Rebased/mergeable

telegraf-tiger · 2024-08-28T21:29:38Z

Thanks so much for the pull request!
🤝 ✒️ Just a reminder that the CLA has not yet been signed, and we'll need it before merging. Please sign the CLA when you get a chance, then post a comment here saying !signed-cla

jeffreyssmith2nd · 2024-08-29T13:56:02Z

content/influxdb/cloud-dedicated/reference/sql/data-types.md

-| INTERVAL  | INTERVAL  | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) |
+| SQL data type | Arrow data type                | Description                                  |
+| :------------ | :----------------------------- | :------------------------------------------- |
+| TIMESTAMP     | Timestamp(Nanosecond, None)    | Nanosecond timestamp with a time zone offset |


It is a bit pedantic, but technically this is a timestamp without a time zone offset. This is what Arrow calls a "point in time".

I think the intention of what you have here is good though, so maybe change the Arrow data type to:
Timestamp(Nanosecond, Some("UTC")) which will also help solidify the change to UTC.

jeffreyssmith2nd · 2024-08-29T13:58:41Z

content/influxdb/clustered/reference/sql/operators/other.md

+  '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset'
 ```

-| UTC with TZ offset       |
-| :----------------------- |
-| 2024-01-01T08:00:00.000Z |
+| Local time with TZ offset |
+| :------------------------ |
+| 2024-01-01T00:00:00-08:00 |
+
+{{% /expand %}}
+{{< /expand-wrapper >}}


I'm currently suggesting this is a bug. Assuming others agree, this will get fixed in DF so that this behaves the same as the code above it.

Or, more accurately, this would be considered a bug in versions of 3.0 that have timezone support turned on.

jeffreyssmith2nd · 2024-08-29T14:00:21Z

content/influxdb/clustered/reference/sql/data-types.md

-| INTERVAL  | INTERVAL  | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) |
+| SQL data type | Arrow data type                | Description                                  |
+| :------------ | :----------------------------- | :------------------------------------------- |
+| TIMESTAMP     | Timestamp(Nanosecond, None)    | Nanosecond timestamp with a time zone offset |


Same comment as above

jeffreyssmith2nd · 2024-08-29T14:00:42Z

content/influxdb/cloud-serverless/reference/sql/operators/other.md

+  '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset'
 ```

-| UTC with TZ offset       |
-| :----------------------- |
-| 2024-01-01T08:00:00.000Z |
+| Local time with TZ offset |
+| :------------------------ |
+| 2024-01-01T00:00:00-08:00 |
+
+{{% /expand %}}
+{{< /expand-wrapper >}}


Same comment as below

jeffreyssmith2nd · 2024-08-29T14:01:01Z

content/influxdb/cloud-serverless/reference/sql/data-types.md

-| INTERVAL  | INTERVAL  | Interval(IntervalUnit::YearMonth) or Interval(IntervalUnit::DayTime) |
+| SQL data type | Arrow data type                | Description                                  |
+| :------------ | :----------------------------- | :------------------------------------------- |
+| TIMESTAMP     | Timestamp(Nanosecond, None)    | Nanosecond timestamp with a time zone offset |


Same as above

jeffreyssmith2nd · 2024-08-29T14:01:13Z

content/influxdb/cloud-dedicated/reference/sql/operators/other.md

+  '2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles' AS 'Local time with TZ offset'
 ```

-| UTC with TZ offset       |
-| :----------------------- |
-| 2024-01-01T08:00:00.000Z |
+| Local time with TZ offset |
+| :------------------------ |
+| 2024-01-01T00:00:00-08:00 |
+
+{{% /expand %}}
+{{< /expand-wrapper >}}


Same as below

content/influxdb/cloud-dedicated/reference/sql/data-types.md

content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md

jstirnaman · 2024-08-29T14:29:18Z

content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md

+
+Converts a value to a date (`YYYY-MM-DD`).
+Supports strings and numeric types as input.
+Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided.


Incomplete sentence.

content/influxdb/cloud-dedicated/reference/sql/functions/time-and-date.md

content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md

content/influxdb/clustered/reference/sql/data-types.md

content/influxdb/clustered/reference/sql/functions/time-and-date.md

jstirnaman · 2024-08-29T14:53:54Z

content/influxdb/clustered/reference/sql/functions/time-and-date.md

+
+Converts a value to a date (`YYYY-MM-DD`).
+Supports strings and numeric types as input.
+Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided.


Incomplete sentence

Co-authored-by: Jason Stirnaman <[email protected]>

telegraf-tiger · 2024-08-29T15:27:56Z

Thanks so much for the pull request!
🤝 ✒️ Just a reminder that the CLA has not yet been signed, and we'll need it before merging. Please sign the CLA when you get a chance, then post a comment here saying !signed-cla

telegraf-tiger · 2024-08-29T19:13:47Z

Thanks so much for the pull request!
🤝 ✒️ Just a reminder that the CLA has not yet been signed, and we'll need it before merging. Please sign the CLA when you get a chance, then post a comment here saying !signed-cla

jstirnaman

~~LGTM. Maybe we need a note about the potential bug Jeff pointed out?~~

sanderson · 2024-08-29T21:05:00Z

@jeffreyssmith2nd I know this is an upstream bug. Are we going to hold off pushing the TZ support out until this bug is fixed? When should these doc changes go live?

jeffreyssmith2nd · 2024-08-29T21:06:32Z

@jeffreyssmith2nd I know this is an upstream bug. Are we going to hold off pushing the TZ support out until this bug is fixed? When should these doc changes go live?

I don't know yet and am headed out for a long weekend. I'll check in with the team Tuesday on if we should delay or not.

Until then, I think we should hold the docs changes.

jstirnaman · 2024-08-29T21:07:08Z

content/influxdb/cloud-serverless/reference/sql/functions/time-and-date.md

+
+Converts a value to a date (`YYYY-MM-DD`).
+Supports strings and numeric types as input.
+Strings are parsed as `YYYY-MM-DD` unless another format is specified. if no Chrono formats are provided.


Incomplete sentence

Strings are parsed as YYYY-MM-DD unless another format is specified. if no Chrono formats are provided.

?

sanderson · 2024-08-29T21:26:02Z

@jstirnaman I think you may have been viewing the diff of an old commit. I went through and fixed all of those.

jeffreyssmith2nd · 2024-09-03T20:25:46Z

@sanderson Still on hold for the docs changes, waiting on some upstream discussion on if the ::timestamp thing is actually a bug or if it is intended behavior.

In the meantime, I'm removing all references to it in the docs where it isn't necessary to prevent any confusion for people down the line.

I will update the blog post and make a corresponding PR here as well once we know for sure what behavior we want out of ::timestamp

sanderson added 3 commits August 28, 2024 15:24

updated timezone-related functions and operators

0d99ebc

Merge branch 'master' into v3/timezone-support

7155905

updated deps

5d35018

sanderson requested review from jstirnaman and jeffreyssmith2nd August 28, 2024 21:29

jeffreyssmith2nd reviewed Aug 29, 2024

View reviewed changes

jstirnaman requested changes Aug 29, 2024

View reviewed changes

Apply suggestions from code review

72ff845

Co-authored-by: Jason Stirnaman <[email protected]>

sanderson added 2 commits August 29, 2024 13:13

updates to address PR feedback

3b6bc8b

Merge branch 'master' into v3/timezone-support

8bcb817

sanderson requested a review from jstirnaman August 29, 2024 19:13

jstirnaman approved these changes Aug 29, 2024

View reviewed changes

jstirnaman requested changes Aug 29, 2024

View reviewed changes

sanderson requested a review from jstirnaman August 29, 2024 21:26

jstirnaman approved these changes Aug 29, 2024

View reviewed changes

sanderson and others added 4 commits September 3, 2024 14:32

Merge branch 'master' into v3/timezone-support

216d86f

Merge branch 'master' into v3/timezone-support

41cd883

chore: remove unnecessary ::timestamp casts (#5596)

5897358

Merge branch 'master' into v3/timezone-support

0f9c24b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add timezone support to v3 SQL docs #5581

Add timezone support to v3 SQL docs #5581

sanderson commented Aug 28, 2024

telegraf-tiger bot commented Aug 28, 2024

jeffreyssmith2nd Aug 29, 2024

jeffreyssmith2nd Aug 29, 2024

jeffreyssmith2nd Aug 29, 2024

jeffreyssmith2nd Aug 29, 2024

jeffreyssmith2nd Aug 29, 2024

jeffreyssmith2nd Aug 29, 2024

jstirnaman Aug 29, 2024

jstirnaman Aug 29, 2024

telegraf-tiger bot commented Aug 29, 2024

telegraf-tiger bot commented Aug 29, 2024

jstirnaman left a comment •

edited

Loading

sanderson commented Aug 29, 2024

jeffreyssmith2nd commented Aug 29, 2024

jstirnaman Aug 29, 2024

sanderson commented Aug 29, 2024

jeffreyssmith2nd commented Sep 3, 2024

Add timezone support to v3 SQL docs #5581

Are you sure you want to change the base?

Add timezone support to v3 SQL docs #5581

Conversation

sanderson commented Aug 28, 2024

telegraf-tiger bot commented Aug 28, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

telegraf-tiger bot commented Aug 29, 2024

telegraf-tiger bot commented Aug 29, 2024

jstirnaman left a comment • edited Loading

Choose a reason for hiding this comment

sanderson commented Aug 29, 2024

jeffreyssmith2nd commented Aug 29, 2024

Choose a reason for hiding this comment

sanderson commented Aug 29, 2024

jeffreyssmith2nd commented Sep 3, 2024

jstirnaman left a comment •

edited

Loading