FROMTIMEZONE

FROMTIMEZONE(date_time, time_zone)[source]

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

This formula assumes the input datetime(s) are expressed in the specified local time of the given IANA time zone identifier (see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) and shifts them to UTC time. 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 in the specified time zone.

Supported types:
- DATETIME
- DATETIME_ARRAY
time_zone (Operand | str) –
The timezone or array of timezones the specified datetimes are in.

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 to UTC time.

Supported types:

DATETIME
DATETIME_ARRAY

Raises:

ValueError – If either input is not a valid type

Examples

Basic usage with a single datetime:

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

Using an array of datetimes with a single timezone:

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

Using a datetime with an array of time zones:

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

Invalid timezone:

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