DateTimeZone.ZoneHours

DateTimeZone

Returns the hour component of the UTC offset for a datetimezone value.

Examples on this page use shared sample tables. View them to understand the input data before reading the examples below.

Syntax

DateTimeZone.ZoneHours(dateTimeZone as datetimezone) as number

Parameters

NameTypeRequiredDescription
dateTimeZonedatetimezoneYesA datetimezone value.

Return Value

number — An integer representing the hours component of the UTC offset (e.g., -5 for UTC-5, 5 for UTC+5:30).

Remarks

DateTimeZone.ZoneHours returns the whole-hours component of the UTC offset for a datetimezone value. For a value with offset +05:30, this returns 5. For -08:00, it returns -8. For UTC (+00:00), it returns 0. To get the minutes component of the offset, use DateTimeZone.ZoneMinutes. Together, these two functions let you extract timezone metadata without fully decomposing the value via DateTimeZone.ToRecord.

A common use case is grouping or filtering datetimezone values by their source timezone — for example, separating events sourced from US Eastern (ZoneHours = -5) vs. UK (ZoneHours = 0) vs. India (ZoneHours = 5). Note that this only identifies the offset, not the named timezone (e.g., UTC-5 could be EST, CDT, or any other timezone with that offset).

DateTimeZone.ZoneHours is most useful when you need only the hours part of the offset quickly. For the complete offset (hours and minutes together), build it from both components: DateTimeZone.ZoneHours(x) * 60 + DateTimeZone.ZoneMinutes(x) gives total offset in minutes.

Examples

Example 1: Extract timezone hour offsets from a set of datetimezone values

#table(
    type table [DTZ = datetimezone, ZoneHours = number],
    {
        {#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0),  DateTimeZone.ZoneHours(#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0))},
        {#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0),   DateTimeZone.ZoneHours(#datetimezone(2024, 3, 15, 14, 0, 0, 1, 0))},
        {#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30),  DateTimeZone.ZoneHours(#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30))},
        {#datetimezone(2024, 3, 16, 17, 45, 0, 0, 0),  DateTimeZone.ZoneHours(#datetimezone(2024, 3, 16, 17, 45, 0, 0, 0))}
    }
)
Result
DTZ
ZoneHours
13/15/2024 1:30:00 PM-5
23/15/2024 1:00:00 PM1
33/16/2024 3:45:00 AM5
43/16/2024 5:45:00 PM0

Example 2: Get the zone hours for a specific datetimezone

#table(
    type table [DTZ = datetimezone, ZoneHours = number],
    {{#datetimezone(2024, 3, 15, 14, 30, 0, 5, 30),
      DateTimeZone.ZoneHours(#datetimezone(2024, 3, 15, 14, 30, 0, 5, 30))}}
)
Result
DTZ
ZoneHours
13/15/2024 9:00:00 AM5

Example 3: Build a total offset in minutes from ZoneHours and ZoneMinutes

#table(
    type table [DTZ = datetimezone, OffsetMinutes = number],
    {
        {#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0),
         DateTimeZone.ZoneHours(#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0)) * 60
           + DateTimeZone.ZoneMinutes(#datetimezone(2024, 3, 15, 8, 30, 0, -5, 0))},
        {#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30),
         DateTimeZone.ZoneHours(#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30)) * 60
           + DateTimeZone.ZoneMinutes(#datetimezone(2024, 3, 16, 9, 15, 0, 5, 30))}
    }
)
Result
DTZ
OffsetMinutes
13/15/2024 1:30:00 PM-300
23/16/2024 3:45:00 AM330

Related Functions

Compatibility

✓ Power BI Desktop✓ Power BI Service✓ Excel Desktop✓ Excel Online✓ Dataflows✓ Fabric Notebooks