# Datetime

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

## [](#_syntax)Syntax

A datetime literal consists of a date fragment and a time fragment, separated by the character `T`.

The date fragment consists of the following values, separated by a `-`:

*   either a four-digit year or a sign with any number of digits for the year (e.g. `+252525` meaning year 252525),
    
*   a two-digit month of the year,
    
*   and a two-digit day of that month.
    

The time fragment consists of the following values, separated by `:`:

*   a two-digit hour between `00` and `24`,
    
*   a two-digit minute between `00` and `59`,
    
*   a two-digit second between `00` and `59` with up to nine digits after the decimal point.
    

Example datetime literals

```typeql
2024-03-30T12:00:00
1920-09-21T09:00:00

#!test[read]
#{{
match
    let $x = 2024-03-30T12:00:00;
    let $y = 1920-09-21T09:00:00;
#}}
```

Example datetime literals (non-4-digit year)

```typeql
+20000-01-01T10:30:00.000
+900-09-21T19:59:59.358

#!test[read]
#{{
match
    let $x = +20000-01-01T10:30:00.000;
    let $y = +900-09-21T19:59:59.358;
#}}
```

## [](#_in_expressions)In expressions

A difference between two datetime values is a duration such that when it is added to the earlier datetime, it produces the later datetime. See the [Duration](../duration/index.md) type reference for more information about datetime-duration arithmetic. The time portion of the result is always under 24 hours.

```typeql
2024-03-30T12:00:00 - 2020-09-21T09:00:00 == P3Y6M9DT3H
2020-09-21T09:00:00 + P3Y6M9DT3H == 2024-03-30T12:00:00
```

## [](#_define_a_datetime_attribute_type)Define a datetime attribute type

```typeql
#!test[schema]
define
  attribute local-sunset value datetime;
```

## [](#_insert_data_that_has_a_datetime_attribute)Insert data that has a datetime attribute

```typeql
#!test[schema]
#{{
define
  entity observation, owns local-sunset;
#}}
#!test[write]
insert
  $o isa observation, has local-sunset 2025-01-10T16:13;
```

## [](#_insert_a_standalone_datetime_attribute)Insert a standalone datetime attribute

```typeql
#!test[write]
insert
  $_ isa local-sunset 2025-01-10T16:13;
```

## [](#_specify_valid_values_for_a_datetime_attribute_type)Specify valid values for a datetime attribute type

```typeql
#!test[schema]
define
  attribute shift-start value datetime @values(2025-01-10T06:00:00, 2025-01-10T14:00:00, 2025-01-10T22:00:00);
```

## [](#_specify_valid_values_for_owning_a_datetime_attribute_type)Specify valid values for owning a datetime attribute type

```typeql
#!test[schema]
define
  entity day-shift owns shift-start @values(2025-01-10T06:00:00, 2025-01-10T14:00:00);
```

## [](#_specify_range_of_valid_values_for_a_datetime_attribute_type)Specify range of valid values for a datetime attribute type

```typeql
#!test[schema]
define
  attribute booking-time value datetime @range(2025-01-01T00:00:00..2025-12-31T23:59:59);
```

## [](#_specify_range_of_valid_values_for_owning_a_datetime_attribute_type)Specify range of valid values for owning a datetime attribute type

```typeql
#!test[schema]
define
  entity business-hours-booking owns booking-time @range(2025-01-01T09:00:00..2025-12-31T17:00:00);
```

## [](#_retrieve_data_by_datetime_attribute)Retrieve data by datetime attribute

```typeql
#!test[read]
match
  $o isa observation, has local-sunset 2025-01-10T16:13;
```

[Date](../date/index.md) [DatetimeTZ](../datetimetz/index.md)

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