TOTIMEZONE

TOTIMEZONE(date_time, time_zone)

Converts a UTC datetime value (or array of datetimes) into a specified time zone.

This formula assumes the input datetime(s) are expressed in Coordinated Universal Time (UTC) and shifts them into the specified local time zone. The time zone must be a valid IANA time zone identifier (see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If the provided time zone is invalid (i.e., not in the tz database), the resulting formula will evaluate to an error value.

Parameters:

• date_time (Operand) –

  The datetime or array of datetimes expressed in UTC.

  Supported types:

  • DATETIME

  • DATETIME_ARRAY

• time_zone (Operand | str) –

  The time zone or array of time zones to convert the UTC datetime(s) into.

  Supported types:

  • STRING

  • STRING_ARRAY

Return type:

Formula

Returns:

A formula object that evaluates to the datetime (or array of datetimes if either input is an array type) converted from UTC into the specified time zone.

Supported types:

• DATETIME

• DATETIME_ARRAY

Raises:

ValueError – If either input is not a valid type.

Examples

Basic usage with a single datetime:

TOTIMEZONE(DATETIME(2024, 3, 10, 19, 0, 0), "America/New_York")
# Returns 2024-03-10 15:00:00

Using an array of datetimes with a single timezone:

TOTIMEZONE(
    [
        DATETIME(2024, 3, 10, 19, 0, 0),
        DATETIME(2024, 6, 1, 13, 30, 0)
    ],
    "America/New_York"
)
# Returns [2024-03-10 15:00:00, 2024-06-01 09:30:00]

Using a datetime with an array of time zones:

TOTIMEZONE(
    DATETIME(2024, 3, 10, 19, 0, 0),
    ["America/New_York", "Europe/London"]
)
# Returns [2024-03-10 15:00:00, 2024-03-10 19:00:00]

Invalid timezone:

TOTIMEZONE(DATETIME(2024, 3, 10, 19, 0, 0), "Invalid/Zone")
# Evaluates to #ERROR