# DatetimeTZ

An [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) compliant date and time type with time zone information.

## [](#_syntax)Syntax

A datetime-tz literal consists of a [datetime](../datetime/index.md) followed by a time zone specification.

A time zone may be specified in two formats:

*   the ISO 8601 time offset from UTC: `±HH`, `±HH:MM`, `±HHMM`, or `Z`;
    
*   the IANA time zone database TZ identifier (usually `<Area>/<Location>`, e.g. `Europe/London`).
    

The IANA TZ identifier is separated from the datetime by a space character.

Example datetime-tz literals

```typeql
2024-03-30T12:00:00Z
1987-12-22T17:29 Asia/Kolkata
1920-04-26T16:30-09:30

#!test[read]
#{{
match
  let $w = 2024-03-30T12:00:00Z;
  let $y = 1887-12-22T17:29 Asia/Kolkata;
  let $z = 1920-04-26T16:30-09:30;
#}}
```

Example datetime-tz literal (non-4-digit year)

```typeql
+20000-01-01T10:30:00.000+0100

#!test[read]
#{{
match
    let $x = +20000-01-01T10:30:00.000+0100;
#}}
```

## [](#_storage_representation)Storage representation

A datetime-tz value is stored as a UTC timestamp and a time zone identifier or offset.

## [](#_comparing_datetime_tz_values)Comparing datetime-tz values

In comparisons, a datetime-tz value is compared to another datetime-tz value by converting both to UTC. In particular, the time zones do not affect the result of the comparison. A later time point in time is always greater than an earlier time point, and two time points at the same instant are equal.

Example datetime-tz comparison

```typeql
2024-01-30T12:00:00 Europe/London == 2024-01-30T08:00:00-04:00
2024-01-30T12:00:00 America/New_York < 2024-01-30T12:00:00Z
2024-01-30T12:00:00+01:00 > 2024-01-30T11:00:00 UTC
```

## [](#_in_expressions)In expressions

A difference between two datetime-tz values is a duration such that when it is added to the earlier datetime-tz, it produces a datetime equal to the later datetime-tz. See the [Duration](../duration/index.md) type reference for more information about datetime-duration arithmetic.

The calendar portion of the result (that is, years, months, and days) is the greatest calendar duration that can be added to the earlier datetime-tz without exceeding the later datetime-tz. The time portion (hours, minutes, seconds, and nanoseconds) is the

Example datetime-tz arithmetic

```typeql
# London DST change occurred on 2024-10-27 02:00:00 BST
# This means that the period from 01:00:00 to 02:00:00 is repeated in the Europe/London timezone
# The repeated hour means that the difference between 2024-10-26T18:00 and 2024-10-27T06:00 is 13 hours, not 12
2024-10-27T06:00 Europe/London - 2024-10-26T18:00 Europe/London == P13H
# Crucially, this also means that the difference between 2024-10-26T18:00 and 2024-10-27T17:30 is 24 hours and 30 minutes
# which is still less than one calendar day
2024-10-27T17:30 Europe/London - 2024-10-26T18:00 Europe/London == PT24H30M
2024-10-27T18:00 Europe/London - 2024-10-26T18:00 Europe/London == P1D
```

## [](#_defining_a_datetime_tz_valued_attribute)Defining a datetime-tz valued attribute

```typeql
#!test[schema]
define
  attribute scheduled-meeting-time value datetime-tz;
```

## [](#_inserting_a_datetime_tz_valued_attribute)Inserting a datetime-tz valued attribute

```typeql
#!test[write]
insert
  $_ isa scheduled-meeting-time 2025-01-10T12:30:00 Europe/London;
```

[Datetime](../datetime/index.md) [Duration](../duration/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/typeql-reference/modules/ROOT/pages/values/datetimetz.adoc) Edit this page on GitHub.