Skip to content

Date, DateTime, Instant and Duration

HQL has four time types. None of them has a literal: a value is built by the type's constructor from ISO 8601 text, the form SQL and JSON write it in.

Type What it holds Written as
Date a calendar date 2026-10-24
DateTime a date and a time of day, with no zone 2026-10-24T09:30:00
Instant a point on the UTC timeline, to the nanosecond 2026-10-24T07:30:00Z
Duration a signed length of time, to the nanosecond PT1H30M
[Date("2026-10-24"), DateTime("2026-10-24T09:30:00"), Instant("2026-10-24T09:30:00+02:00"), Duration("PT1H30M")]
[2026-10-24, 2026-10-24T09:30:00, 2026-10-24T07:30:00Z, PT1H30M]

An Instant is read with its offset or Z and written in UTC, so 09:30+02:00 is 07:30Z. A DateTime names a wall-clock reading and carries no offset; it becomes an Instant only through a zone. A Duration counts days as 24 hours and has no months or years, whose length depends on the date they start from.

A constructor also takes named parts: Date(year =, month =, day =), DateTime(date, hour =, minute =), Instant(unix_seconds =) and Duration(hours =, minutes =, ...). Text that does not parse, or a part out of range, fails when the program runs, and the error names it:

Date(year = 2026, month = 2, day = 30)
execute failure[invalid-argument]: year 2026, month 2, day 30 is not a date
 --> <expression>:1:1
  |
1 | Date(year = 2026, month = 2, day = 30)
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Order and equality

Each time type is Orderable: ==, <, sort, min and max compare two dates, two date-times or two instants by time, and two durations by length. Two instants written with different offsets are equal when they name one point:

[Date("2026-10-24"), Date("2025-12-31"), Date("2026-01-01")] | sort
[2025-12-31, 2026-01-01, 2026-10-24]

+ and - take two Durations, and no other time type. An instant or a date moves by a named operation of the time module:

Duration("PT1H") + Duration(minutes = 30) > Duration("PT1H15M")
true

abs, which the prelude's math module declares over numbers, also takes a Duration and gives its length without its sign, so the gap between two times reads the same whichever is subtracted from which:

[abs(Duration("PT1H") - Duration("PT90M")), Duration("PT2H").abs()]
[PT30M, PT2H]

The time module

Every operation over a time value is in the module time, which is not in the prelude: a program writes import time. The operations below are receivers, d.year(), which import time reaches; a call written without the module's name, now(), needs from time import *.

Parts and calendar arithmetic

year, month, day, weekday (Monday is 1) and iso_week read a date's parts, and hour, minute and second a date-time's:

import time
d = Date("2026-10-24")
[d.year(), d.month(), d.day(), d.weekday(), d.iso_week()]
[2026, 10, 24, 6, 43]

add_days, add_months and add_years move a date by calendar units. A month added to January 31 lands on the last day of February. truncate gives the start of the Week, Month, Quarter or Year containing a date, the key a grouping by period uses:

import time
[Date("2026-01-31").add_months(1), Date("2026-10-24").add_days(10), Date("2026-11-12").truncate(Month)]
[2026-02-28, 2026-11-03, 2026-11-01]

days_since counts the days between two dates, since gives the Duration between two instants, and plus and minus move an instant by one:

import time
Instant("2026-10-24T07:30:00Z").since(Instant("2026-10-23T22:00:00Z"))
PT9H30M

Zones

Zone(name) names a zone: an IANA name such as "Europe/Berlin", "UTC", or a fixed offset "+05:30". reading.in_zone(zone) gives the instant a wall-clock reading names there, and instant.at(zone) the reading an instant has there:

from time import *
berlin = Zone("Europe/Berlin")
meeting = DateTime("2026-11-02T10:00:00").in_zone(berlin)
[str(meeting), str(meeting.at(Zone("America/New_York")))]
["2026-11-02T09:00:00Z", "2026-11-02T04:00:00"]

When clocks move forward, a reading inside the skipped hour moves forward by the gap; when they move back, a reading that happens twice is the earlier instant. On 2026-03-29 Berlin skips 02:00 to 03:00, and on 2026-10-25 it repeats 02:00 to 03:00:

from time import *
[DateTime("2026-03-29T02:30:00").in_zone(Zone("Europe/Berlin")), DateTime("2026-10-25T02:30:00").in_zone(Zone("Europe/Berlin"))]
[2026-03-29T01:30:00Z, 2026-10-25T00:30:00Z]

A zone's rules come from a time-zone database: the host's where it has one, else the one compiled into hql. A reading in the future can move when that database changes its rules, so hql --version names the database on its second line: system for the host's, or the bundled database's release, 2026e, bundled:

$ hql --version
hql 0.6.0
time-zone database: system

Text in other forms

fmt(pattern) writes a value through a strftime pattern, and parse_date, parse_datetime and parse_instant read text through one. The directives are %Y %m %d %H %M %S %f %z %Z %j %a %A %b %B %p %%:

import time
[Date("2026-10-24").fmt("%A, %d %B %Y"), str("24.10.2026".parse_date("%d.%m.%Y"))]
["Saturday, 24 October 2026", "2026-10-24"]

to_date, to_datetime, to_instant and to_duration read ISO 8601 text as an Option: the value where the text is one, and none where it is not. A parse function gives none the same way:

import time
["2026-10-24".to_date(), "24 Oct".to_date()]
[2026-10-24, none]

A parse function given no pattern reads what its to_* reads: s.parse_date() is s.to_date(), and the same for parse_datetime and parse_instant:

import time
["1982-05-09".parse_date(), "09.05.1982".parse_date()]
[1982-05-09, none]

The evaluation clock

now() gives the evaluation instant, today() the date it falls on in the evaluation zone, and local_zone() that zone. Each is read once per evaluation, so two calls in one program agree. --now and --zone fix them, which makes a program that reads the clock repeatable:

from time import *
[str(now()), str(today()), local_zone().name]
["2026-10-24T23:30:00Z", "2026-10-25", "Europe/Berlin"]

Without --zone, the zone is the one TZ names, else the host's.

Time in data

Every format writes a time value as its ISO 8601 text, a JSON string:

{on: Date("2026-10-24"), took: Duration("PT1H30M")}
{
  "on": "2026-10-24",
  "took": "PT1H30M"
}

Reading is the other way round only where a type says so. A JSON or YAML string that looks like a date stays a String; a field declared Date, DateTime, Instant or Duration reads its text as one, and text that is not one fails the read:

type Event {
    name : String
    on   : Date
}
Data("{\"name\": \"launch\", \"on\": \"2026-10-24\"}", Json) | Event
Event(name = "launch", on = 2026-10-24)

SQL tables read the same way. A PostgreSQL DATE, TIMESTAMP and TIMESTAMPTZ column reads as a Date, a DateTime and an Instant, and Spark's DATE, TIMESTAMP_NTZ and TIMESTAMP likewise; a field of a time type written to SQLite, or to any text column, is its ISO 8601 text.