feat: Update for latest SQL timezone behavior #5657

jeffreyssmith2nd · 2024-10-22T15:23:38Z

Closes #

Describe your proposed changes here.

Signed the InfluxData CLA
(if necessary)
Rebased/mergeable

sanderson

@jeffreyssmith2nd Thanks for this! I added some suggestions.

sanderson · 2024-10-22T20:19:51Z

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

+Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC.
+
+```sql
+tz(time[, timezone])


Suggested change

tz(time[, timezone])

tz(time_expression[, timezone])

sanderson · 2024-10-22T20:20:01Z

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

+
+##### Arguments
+
+- **expression**: time to operate on.


Suggested change

- **expression**: time to operate on.

- **time_expression**: Time to operate on.

sanderson · 2024-10-22T20:24:04Z

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

+- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided
+  The function returns the timestamp cast to the correct timezone.
+  If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.


Suggested change

- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided

The function returns the timestamp cast to the correct timezone.

If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.

- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

to cast the value into. Default is `'UTC'`.

The function returns the timestamp cast to the specified timezone.

If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error.

sanderson · 2024-10-22T21:10:13Z

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

+##### What is the difference between tz and AT TIME ZONE?
+`tz` and [AT TIME ZONE](../operators/other/#at-time-zone) have similar behavior that differs when the input timestamp **does not** have a timezone associated with it.
+
+When a timestamp does not have a timezone associated with it (the default behavior in InfluxDB 3.0), `AT TIME ZONE` will cast a timestamp to the "wall clock" time in a particular time zone. This is the moment in time something would be experienced in a given time zone. This is a good way to define bounds on a query when you want them relative to some known range in a timezone (for example your local time).
+If a timezone is associated with the timestamp, then `AT TIME ZONE` will behave the same as `tz`.
+
+`tz` will **always** cast a timestamp to the "absolute" time in a particular time zone. This is a time relative to the unix epoch that has then be converted to that point in time in a given time zone. This is useful when you have data that was written as UTC or epoch timestamps, and you would like to view them in a specific timezone.
+
+{{< expand-wrapper >}}
+{{% expand "View `tz` and `::timestamp` comparison" %}}
+```sql
+SELECT
+  '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,
+  tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;
+```
+
+| time_timestamp               | time_tz                    |
+| :--------------------------- | :------------------------- |
+| 2024-04-01T00:00:20+02:00    | 2024-04-01T02:00:20+02:00  |
+
+{{% /expand %}}
+{{< /expand-wrapper >}}


Suggested change

##### What is the difference between tz and AT TIME ZONE?

`tz` and [AT TIME ZONE](../operators/other/#at-time-zone) have similar behavior that differs when the input timestamp **does not** have a timezone associated with it.

When a timestamp does not have a timezone associated with it (the default behavior in InfluxDB 3.0), `AT TIME ZONE` will cast a timestamp to the "wall clock" time in a particular time zone. This is the moment in time something would be experienced in a given time zone. This is a good way to define bounds on a query when you want them relative to some known range in a timezone (for example your local time).

If a timezone is associated with the timestamp, then `AT TIME ZONE` will behave the same as `tz`.

`tz` will **always** cast a timestamp to the "absolute" time in a particular time zone. This is a time relative to the unix epoch that has then be converted to that point in time in a given time zone. This is useful when you have data that was written as UTC or epoch timestamps, and you would like to view them in a specific timezone.

{{< expand-wrapper >}}

{{% expand "View `tz` and `::timestamp` comparison" %}}

```sql

SELECT

'2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,

tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;

```

| time_timestamp | time_tz |

| :--------------------------- | :------------------------- |

| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 |

{{% /expand %}}

{{< /expand-wrapper >}}

##### Differences between tz and AT TIME ZONE

`tz` and [`AT TIME ZONE`](/influxdb/cloud-dedicated/reference/sql/operators/other/#at-time-zone)

differ when the input timestamp **does not** have a timezone.

- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the

`AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset

(also known as the "wall clock" time)--for example:

```sql

'2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles'

-- Returns

2024-01-01T00:00:00-08:00

```

- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE`

operator return the timestamp converted to the time in the specified timezone--for example:

```sql

'2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles'

tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles')

-- Both return

2023-12-31T16:00:00-08:00

```

- `tz()` always converts the input timestamp to the specified time zone.

If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example:

```sql

tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles')

-- Returns

2023-12-31T16:00:00-08:00

```

```sql

tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles')

-- Returns

2023-12-31T15:00:00-08:00

```

{{< expand-wrapper >}}

{{% expand "View `tz` and `::timestamp` comparison" %}}

```sql

SELECT

'2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,

tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;

```

| time_timestamp | time_tz |

| :--------------------------- | :------------------------- |

| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 |

{{% /expand %}}

{{< /expand-wrapper >}}

Ah I like this way of describing it, much clearer!

sanderson · 2024-10-22T21:11:05Z

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

+Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC.
+
+```sql
+tz(time[, timezone])


Suggested change

tz(time[, timezone])

tz(time_expression[, timezone])

sanderson · 2024-10-22T21:12:47Z

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

+Converts a timestamp to a provided timezone. If the second argument is not provided, it defaults to UTC.
+
+```sql
+tz(time[, timezone])


Suggested change

tz(time[, timezone])

tz(time_expression[, timezone])

sanderson · 2024-10-22T21:12:58Z

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

+
+##### Arguments
+
+- **expression**: time to operate on.


Suggested change

- **expression**: time to operate on.

- **time_expression**: Time to operate on.

sanderson · 2024-10-22T21:13:28Z

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

+- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided
+  The function returns the timestamp cast to the correct timezone.
+  If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.


Suggested change

- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided

The function returns the timestamp cast to the correct timezone.

If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.

- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

to cast the value into. Default is `'UTC'`.

The function returns the timestamp cast to the specified timezone.

If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error.

sanderson · 2024-10-22T21:13:58Z

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

+- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided
+  The function returns the timestamp cast to the correct timezone.
+  If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.


Suggested change

- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided

The function returns the timestamp cast to the correct timezone.

If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.

- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

to cast the value into. Default is `'UTC'`.

The function returns the timestamp cast to the specified timezone.

If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error.

sanderson · 2024-10-22T21:14:34Z

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

+##### What is the difference between tz and AT TIME ZONE?
+`tz` and [AT TIME ZONE](../operators/other/#at-time-zone) have similar behavior that differs when the input timestamp **does not** have a timezone associated with it.
+
+When a timestamp does not have a timezone associated with it (the default behavior in InfluxDB 3.0), `AT TIME ZONE` will cast a timestamp to the "wall clock" time in a particular time zone. This is the moment in time something would be experienced in a given time zone. This is a good way to define bounds on a query when you want them relative to some known range in a timezone (for example your local time).
+If a timezone is associated with the timestamp, then `AT TIME ZONE` will behave the same as `tz`.
+
+`tz` will **always** cast a timestamp to the "absolute" time in a particular time zone. This is a time relative to the unix epoch that has then be converted to that point in time in a given time zone. This is useful when you have data that was written as UTC or epoch timestamps, and you would like to view them in a specific timezone.
+
+{{< expand-wrapper >}}
+{{% expand "View `tz` and `::timestamp` comparison" %}}
+```sql
+SELECT
+  '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,
+  tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;
+```
+
+| time_timestamp               | time_tz                    |
+| :--------------------------- | :------------------------- |
+| 2024-04-01T00:00:20+02:00    | 2024-04-01T02:00:20+02:00  |
+
+{{% /expand %}}
+{{< /expand-wrapper >}}


Suggested change

##### What is the difference between tz and AT TIME ZONE?

`tz` and [AT TIME ZONE](../operators/other/#at-time-zone) have similar behavior that differs when the input timestamp **does not** have a timezone associated with it.

When a timestamp does not have a timezone associated with it (the default behavior in InfluxDB 3.0), `AT TIME ZONE` will cast a timestamp to the "wall clock" time in a particular time zone. This is the moment in time something would be experienced in a given time zone. This is a good way to define bounds on a query when you want them relative to some known range in a timezone (for example your local time).

If a timezone is associated with the timestamp, then `AT TIME ZONE` will behave the same as `tz`.

`tz` will **always** cast a timestamp to the "absolute" time in a particular time zone. This is a time relative to the unix epoch that has then be converted to that point in time in a given time zone. This is useful when you have data that was written as UTC or epoch timestamps, and you would like to view them in a specific timezone.

{{< expand-wrapper >}}

{{% expand "View `tz` and `::timestamp` comparison" %}}

```sql

SELECT

'2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,

tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;

```

| time_timestamp | time_tz |

| :--------------------------- | :------------------------- |

| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 |

{{% /expand %}}

{{< /expand-wrapper >}}

##### Differences between tz and AT TIME ZONE

`tz` and [`AT TIME ZONE`](/influxdb/clustered/reference/sql/operators/other/#at-time-zone)

differ when the input timestamp **does not** have a timezone.

- When using an input timestamp that does not have a timezone (the default behavior in InfluxDB) with the

`AT TIME ZONE` operator, the operator returns the the same timestamp, but with a timezone offset

(also known as the "wall clock" time)--for example:

```sql

'2024-01-01 00:00:00'::TIMESTAMP AT TIME ZONE 'America/Los_Angeles'

-- Returns

2024-01-01T00:00:00-08:00

```

- When using an input timestamp with a timezone, both the `tz()` function and the `AT TIME ZONE`

operator return the timestamp converted to the time in the specified timezone--for example:

```sql

'2024-01-01T00:00:00-00:00' AT TIME ZONE 'America/Los_Angeles'

tz('2024-01-01T00:00:00-00:00', 'America/Los_Angeles')

-- Both return

2023-12-31T16:00:00-08:00

```

- `tz()` always converts the input timestamp to the specified time zone.

If the input timestamp does not have a timezone, the function assumes it is a UTC timestamp--for example:

```sql

tz('2024-01-01 00:00:00'::TIMESTAMP, 'America/Los_Angeles')

-- Returns

2023-12-31T16:00:00-08:00

```

```sql

tz('2024-01-01T00:00:00+1:00', 'America/Los_Angeles')

-- Returns

2023-12-31T15:00:00-08:00

```

{{< expand-wrapper >}}

{{% expand "View `tz` and `::timestamp` comparison" %}}

```sql

SELECT

'2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' as time_timestamp,

tz('2024-04-01T00:00:20', 'Europe/Brussels') as time_tz;

```

| time_timestamp | time_tz |

| :--------------------------- | :------------------------- |

| 2024-04-01T00:00:20+02:00 | 2024-04-01T02:00:20+02:00 |

{{% /expand %}}

{{< /expand-wrapper >}}

Co-authored-by: Scott Anderson <[email protected]>

sanderson

🚀 Looks great!

* updated timezone-related functions and operators * updated deps * Apply suggestions from code review Co-authored-by: Jason Stirnaman <[email protected]> * updates to address PR feedback * chore: remove unnecessary ::timestamp casts (#5596) * feat: Update for latest SQL timezone behavior (#5657) * feat: Update for latest SQL timezone behavior * fix: cleanup and improve wording Co-authored-by: Scott Anderson <[email protected]> --------- Co-authored-by: Scott Anderson <[email protected]> --------- Co-authored-by: Jason Stirnaman <[email protected]> Co-authored-by: Jeffrey Smith II <[email protected]>

feat: Update for latest SQL timezone behavior

2917e41

jeffreyssmith2nd marked this pull request as ready for review October 22, 2024 15:41

jeffreyssmith2nd requested review from jstirnaman and sanderson October 22, 2024 18:33

sanderson requested changes Oct 22, 2024

View reviewed changes

fix: cleanup and improve wording

7a84ef8

Co-authored-by: Scott Anderson <[email protected]>

sanderson approved these changes Oct 23, 2024

View reviewed changes

jeffreyssmith2nd merged commit 4ef4aa5 into v3/timezone-support Oct 23, 2024
1 check passed

jeffreyssmith2nd deleted the smith/updated-timezone-docs branch October 23, 2024 17:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Update for latest SQL timezone behavior #5657

feat: Update for latest SQL timezone behavior #5657

jeffreyssmith2nd commented Oct 22, 2024

sanderson left a comment

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

jeffreyssmith2nd Oct 23, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson Oct 22, 2024

sanderson left a comment

	- expression: time to operate on.
	- time_expression: Time to operate on.

-- **timezone**: Optional [timezone db string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) into which the value should be cast. Defaults to "UTC" if not provided
-  The function returns the timestamp cast to the correct timezone.
-  If an incorrect timezone string is passed, or the wrong datatype is provided, the function returns an error.
+- **timezone**: [Timezone string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+  to cast the value into. Default is `'UTC'`.
+  The function returns the timestamp cast to the specified timezone.
+  If an incorrect timezone string is passed or the wrong datatype is provided, the function returns an error.

feat: Update for latest SQL timezone behavior #5657

feat: Update for latest SQL timezone behavior #5657

Conversation

jeffreyssmith2nd commented Oct 22, 2024

sanderson left a 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

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

sanderson left a comment

Choose a reason for hiding this comment