Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/ Documentation version: v5.3.2 # Temporal types Temporal values are used for the storage, manipulation, and retrieval of date and time information. GQL comes with built-in support for temporal values that can be stored as property values on nodes and edges. The following sections explain the temporal types and how to use them. ## Categories of temporal values Temporal values fall into two categories: temporal instant values and temporal duration values. - Temporal instant value: Represents a specific point in time, such as a date or a time. - Temporal duration value: Represents a time difference between two temporal instant values. ### Temporal instants Temporal instants can be specified using the following elements: date, time, and time zone. These elements can be combined in various ways to create a temporal instant. Temporal instant types include zoned datetime, local datetime, date, zoned time, and local time. - A zoned datetime includes a time, a date, and a time zone. It's the most specific as it indicates the exact moment in time worldwide. - A local datetime includes a time and a date but doesn't include a time zone. It specifies a moment in time but only for a local region, not globally. - A date signifies a calendar date (year, month, day) that remains unaffected by time zone considerations. - A zoned time includes a time and a time zone. It represents the same clock time, observed on different days, in a specific time zone. - A local time includes only a time. It's the least specific, representing a time of day without any date or time zone context. The following table lists the temporal instant types, their declaration keywords, and value ranges. | Type | Declaration keywords | Date support | Time support | Time zone support | Range | Zoned datetime | `ZONED DATETIME` | Yes | Yes | Yes | -9999-01-01T00:00:00.000000+1400 ~ 9999-12-31T23:59:59.999999-1200 | Local datetime | `LOCAL DATETIME` | Yes | Yes | No | -9999-01-01T00:00:00.000000 ~ 9999-12-31T23:59:59.999999 | Date | `DATE` | Yes | No | No | -9999-01-01 ~ 9999-12-31 | Zoned time | `ZONED TIME` | No | Yes | Yes | 00:00:00.000000+1400 ~ 23:59:59.99999-1200 | Local time | `LOCAL TIME` | No | Yes | No | 00:00:00.000000 ~ 23:59:59.999999 - The declaration keywords are used to specify the temporal instant type when you create a property. - The range format is an example. You can specify a temporal instant value in the format defined by you. For more information, see [Temporal instant value formats](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/#temporal_value_formats). ### Temporal durations A temporal duration can be specified using the following elements: years, months, days, hours, minutes, seconds, milliseconds, and microseconds. These elements can be combined in various ways to create a temporal duration. The keyword `DURATION` is used to declare a duration. A temporal duration value can be positive, zero, or negative. For how to specify a duration, see [Specify durations](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/#specify_durations). ## Temporal value formats You have the flexibility to define the format in which you want to represent these values. However, the chosen format must adhere to the guidelines provided by the [ISO 8601 standard](https://www.iso.org/iso-8601-date-and-time-format.html). Once you specify the desired format, you should provide the temporal value in that format. In the following example, `%Y-%m-%dT%H:%M:%S` is the temporal value format defined by you, and `2012-03-04T05:06:07.0890` is the value specified in the format. ```` local_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS localdatetime ```` Note - In GQL, you insert a property value of the temporal types by using a [temporal function](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/temporal/). - If you specify a temporal value in the default format, you can omit the value format. For example, you can directly use `local_datetime("2012-03-04T05:06:07.0890")` without specifying the format in the above example. A temporal value format is a string that consists of the following elements: | Element | Description | Range | `%Y` | A year | -9999 ~ 9999 | `%y` | A two-digit year | 00 ~ 99 | `%m` | A two-digit month of the year | 01 ~ 12 | `%d` | A two-digit day of the month | 01 ~ 31 | `%H` | A hour of the day, 24-hour clock | 00 ~ 23 | `%I` | A hour of the day, 12-hour clock | 01 ~ 12 | `%M` | A two-digit minute of the hour | 00 ~ 59 | `%S` | A two-digit second of the minute. It includes fractional seconds, with up to six digits after the decimal point. When no fractional seconds are specified, zeros are padded to the right of the decimal point. | 00 ~ 59.999999 | `%f` | Fractional seconds | 000000 ~ 999999 | `%a` | An abbreviated weekday name | Mon, Tue, Wed, Thu, Fri, Sat, Sun | `%A` | A full weekday name | Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday | `%b` | An abbreviated month name | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec | `%B` | A full month name | January, February, March, April, May, June, July, August, September, October, November, December | `%z` | Timezone offset relative to UTC. For example, `-0430` refers to 4 hours and 30 minutes behind UTC. If the offset is zero, `+0000` is used. | -1200 ~ +1400 | `%Ez` | Similar to `%z`, the difference is that a colon is needed between the hours and minutes, for example, `-04:30`. If the offset is zero, `+00:00` is used. | -12:00 ~ +14:00 ### Specify times The `%H/%I`, `%M`, `%S`, and `%z/%Ez` elements are used to format the time. For example, `05:06:07.089` is a time specified in the format `%H:%M:%S`. The element `%H/%I` must be specified in the format. A time is either a zoned time with the default format `%H:%M:%S %z`, or a local time with the default format `%H:%M:%S`. If the time zone is specified, the time is a zoned time; otherwise, it is a local time. For example: - A local time: ```` local_time("05:06:07.089", "%H:%M:%S") AS localtime ```` - A zoned time: ```` zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez") AS zonetime ```` It is not required to specify the trailing zeros for fractional seconds. For example, `05:06:07.089000` can be specified as `05:06:07.089`. Note that if the number of fractional seconds is less than the maximum number of fractional seconds, zeros are padded to the end of the number to reach the required length. If the time elements are not specified, the time defaults to `00:00:00.000000`. #### Specify time zones A time zone is a region of the globe that observes a uniform standard time for legal, commercial, and social purposes. It is represented by the time zone displacement, which is the difference between the local time and Universal Coordinated Time (UTC). The `%z` or `%Ez` element is used to format the time zone displacement. When the time zone displacement is used with the local time, results are converted to UTC. For information about the time zone identifiers and their corresponding displacements, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When specifying a time zone displacement from UTC, the following guidelines apply: - The displacement is parsed as a four-digit number, such as `HHMM`, where `HH` is the hours and `MM` is the minutes. An optional colon (`:`) can be used to separate the hours and minutes, for example, `+08:00`. - When using `%z` to format the time zone, the value must be a four-digit number. - When using `%Ez` to format the time zone, the value must be a four-digit number with a mandatory colon separating the hours and minutes. - The displacement is positive if the local time is ahead of UTC, indicated by a `+` sign or no sign. - The displacement is negative if the local time is behind UTC, indicated by a `-` sign. - When the time zone element and the corresponding value are not specified in a zoned time or zoned datetime, the time zone defaults to `+00:00` when the displacement is zero. The following exemplifies the use of the `%z` element to specify a time zone displacement. `2016-09-20T01:01:01.123456` is the local time and `+0800` is the displacement. The returned value `2016-09-20T01:01:01.123456+08:00` is Universal Coordinated Time. ```` zoned_datetime("2016-09-20T01:01:01.123456 +0800", "%Y-%m-%dT%H:%M:%S %z") AS zoneddatetime ```` ### Specify dates The `%Y/%y`, `%m/%b/%B`, `%d`, and `%a/%A` elements are used to format the date. For example, `Tue, 2016-09-20` is a date specified in the format `%a, %Y-%m-%d`. The `%Y/%y`, `%m/%b/%B`, and `%d` must be specified in the format. The default format for a date is `%Y-%m-%d`. If the date and the matched day of the week are specified, the day of the week is ignored in the result. For example: ```` date("Tue, 2016-09-20", "%a, %Y-%m-%d") AS d ```` Return: ```` +------------+ | d | +------------+ | 2016-09-20 | +------------+ ```` In the above example, `Tue, 2016-09-20T01:01:01` is equivalent to `2016-09-20T01:01:01`. If the date and the day of the week do not match, a parsing error is returned. ### Specify datetimes A datetime is a combination of a date and a time. You can specify a datetime by using the date and time elements. A delimiter, such as `T`, must be used to separate the date and time elements. For example, `2016-09-20T01:01:01` is a datetime specified in the format `%Y-%m-%dT%H:%M:%S`. The elements `%Y/%y`, `%m/%b/%B`, and `%d` must be specified in the format. A datetime can be either a zoned datetime with the default format `%Y-%m-%dT%H:%M:%S %z`, or a local datetime with the default format `%Y-%m-%dT%H:%M:%S`. If the time zone is specified, the datetime is a zoned datetime; otherwise, it is a local datetime. For example: - A datetime without a time zone: ```` local_datetime("2016-09-20T01:01:01.123456", "%Y-%m-%dT%H:%M:%S") AS localdatetime ```` Return: ```` +----------------------------+ | localdatetime | +----------------------------+ | 2016-09-20T01:01:01.123456 | +----------------------------+ ```` - A datetime with a time zone: ```` zoned_datetime("2016-09-20T01:01:01.123456 +08:00", "%Y-%m-%dT%H:%M:%S %Ez") AS zoneddatetime ```` Return: ```` +-----------------------------+ | zoneddatetime | +-----------------------------+ | 2016-09-19T17:01:01.123456Z | +-----------------------------+ ```` ### Specify durations Every temporal duration only uses the temporal duration units from exactly one of the following temporal duration unit groups: - Year and month-based duration unit group: `years` and `months`, for example, `duration({years:100, months:1})`. - Day and time-based duration unit group: `days`, `hours`, `minutes`, `seconds`, `milliseconds`, and `microseconds`, for example, `duration({days:1, hours:2, minutes:3, seconds:4, milliseconds:4, microseconds:5})`. For each unit group, the unit values are specified as a map. The unit values are positive integers, zero, or negative integers. The unit values can be combined in various ways to create a temporal duration. The unit in the map is optional. If the unit is not specified, the value defaults to zero. For how to specify a duration, see [duration()](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/temporal/#duration). ## Operators or functions for temporal type values The following table lists the operators or functions that can be used with temporal type values. For more information, see [Operations between temporal instants and durations](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/temporal/#operations_between_temporal_instants_and_durations). | Operand 1 | Function/Operator | Operand 2 | Result | temporal instant | `duration_between()` | temporal instant | temporal duration | temporal instant | `+` or `-` | temporal duration | temporal instant | temporal duration | `+` | temporal instant | temporal instant | temporal duration | `+` or `-` | temporal duration | temporal duration | temporal duration | `*` or `/` | number | temporal duration | number | `*` | temporal duration | temporal duration ## Components of temporal instants You can use the period (`.`) operator to access the components of temporal instants. The following table lists the supported components and provides examples on how to access them. | Component | Description | Temporal function example | Temporal literal example | `year` | The year of the temporal instant | `RETURN zoned_datetime("2016-09-20T01:01:01 +08:00", "%Y-%m-%dT%H:%M:%S %Ez").year AS year` | `RETURN DATETIME "2016-09-20T01:01:01+0800".year AS year` | `month` | The month of the temporal instant | `RETURN date("Tue, 2016-09-20", "%a, %Y-%m-%d").month AS month` | `RETURN DATE "2016-09-20".month AS month` | `day` | The day of the temporal instant | `RETURN local_datetime("2016-09-20T01:01:01", "%Y-%m-%dT%H:%M:%S").day AS day` | `RETURN DATETIME "2016-09-20T01:01:01".day AS day` | `hour` | The hour of the temporal instant | `RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").hour AS hour` | `RETURN TIME "05:06:07.089+0800".hour AS hour` | `minute` | The minute of the temporal instant | `RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").minute AS minute` | `RETURN TIME "05:06:07.089+0800".minute AS minute` | `second` | The second of the temporal instant | `RETURN local_time("05:06:07.089", "%H:%M:%S").second AS second` | `RETURN TIME "05:06:07.089".second AS second` When you access a component that is not included in the temporal instant, the following rules apply: - When accessing `year`, `month`, or `day` of a zoned time (`ZONED TIME`) or a local time (`LOCAL TIME`), the corresponding value of the current date is returned. - When accessing `hour`, `minute`, or `second` of a date (`DATE`), the value `0` is returned for all three components. ## More information - [Temporal functions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/temporal/) - [Temporal literals](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/literals/#temporal_literals)