DateTime ​

DateTime represents an instant with whole-second precision. The value is interpreted as a Unix-second count; its range is 1970-01-01 00:00:00 through 2106-02-07 06:28:15 in UTC.

Syntax ​

DateTime
DateTime('timezone')

• timezone — An IANA timezone name, such as 'UTC' or 'Europe/Berlin'. The default is 'UTC'.

Use DateTime64 for fractional seconds or a wider calendar range.

Usage Remarks ​

Integer input is Unix seconds. Zone-free text is interpreted in the declared timezone. Text containing only a date represents midnight in that zone. Display uses the declared timezone.

Ambiguous local times during a backward clock change and nonexistent local times during a forward change are rejected. The type declaration establishes a timezone for the value; it does not accept an independently chosen zone per row.

Casting to INTEGER returns epoch seconds. Adding or subtracting an integer moves the timestamp by that many elapsed seconds. Calendar intervals preserve local calendar rules and can fail when the resulting local time is ambiguous or nonexistent.

Examples ​

Inserting and selecting timestamps ​

CREATE TABLE events(id UInt32, occurred_at DateTime('UTC'));
INSERT INTO events VALUES (1, '2025-03-05 12:30:00');

SELECT id, occurred_at, occurred_at + 60 AS one_minute_later
FROM events
FORMAT csv;

1,"2025-03-05 12:30:00","2025-03-05 12:31:00"

Converting Unix seconds ​

SELECT CAST(1 AS DateTime('UTC')),
       CAST(CAST('1970-01-01 00:00:01' AS DateTime) AS INTEGER)
FORMAT csv;

"1970-01-01 00:00:01",1

Interpreting local text ​

The same instant has different local representations:

SELECT CAST('2025-01-15 12:00:00' AS DateTime('UTC'))
     = CAST('2025-01-15 13:00:00' AS DateTime('Europe/Berlin'))
FORMAT csv;

1