Date & Time

OcaltQL has three temporal types: DATE, TIME, and DATE AND TIME. They are constructed with NEW, manipulated with CALCULATE, inspected with GET, formatted with FORMAT, and converted between timezones with CONVERT TIMEZONE.

Constructing Temporal Values

Use NEW without FROM to get the current date, time, or datetime. Use FROM to construct from a specific string.

Current Date, Time, and Datetime
NEW DATE AND TIME SET ?dt
AFTER NEW DATE SET ?date
AFTER NEW TIME SET ?time
From a Specific Value
NEW DATE AND TIME FROM "2026-06-27 18:25:00" SET ?dt
AFTER NEW DATE FROM "2026-06-27" SET ?date
AFTER NEW TIME FROM "18:25:00" SET ?time

Temporal Arithmetic

CALCULATE handles date and time math using natural unit keywords: DAY, WEEK, MONTH, YEAR, HOURS, MINUTES. LAST DAY and FIRST DAY return the last and first day of the month the date falls in.

Date Arithmetic
NEW DATE SET ?date
AFTER CALCULATE ?date + 1 DAY SET ?tomorrow
AFTER CALCULATE ?date - 1 DAY SET ?yesterday
AFTER CALCULATE ?date + 1 WEEK SET ?nextweek
AFTER CALCULATE ?date - 1 WEEK SET ?lastweek
AFTER CALCULATE ?date + 1 MONTH SET ?nextmonth
AFTER CALCULATE ?date - 1 MONTH SET ?lastmonth
AFTER CALCULATE ?date + 1 YEAR SET ?nextyear
AFTER CALCULATE ?date - 1 YEAR SET ?lastyear
Time Arithmetic
NEW DATE AND TIME SET ?dt
AFTER CALCULATE ?dt + 30 MINUTES SET ?later
AFTER CALCULATE ?dt - 2 HOURS SET ?earlier
First and Last Day of Month
NEW DATE SET ?date
AFTER CALCULATE ?date FIRST DAY SET ?firstdayofmonth
AFTER CALCULATE ?date LAST DAY SET ?lastdayofmonth

Extracting Parts

GET extracts a specific component from a date, time, or datetime variable. Day and month names are available in both full and short form.

Day and Month Names
NEW DATE SET ?date
AFTER GET ?date DAY FULLNAME SET ?todayname
AFTER GET ?date DAY SHORTNAME SET ?shortname
AFTER GET ?date MONTH FULLNAME SET ?monthname
AFTER GET ?date MONTH SHORTNAME SET ?shortmonth
Numeric Parts
NEW DATE AND TIME SET ?dt
AFTER NEW TIME SET ?time
AFTER GET ?dt YEAR SET ?year
AFTER GET ?dt MONTH SET ?month
AFTER GET ?dt DAY SET ?day
AFTER GET ?dt HOUR SET ?h
AFTER GET ?dt MINUTE SET ?m
AFTER GET ?dt SECOND SET ?s
AFTER GET ?time HOUR SET ?hour
AFTER GET ?time MINUTE SET ?minute
AFTER GET ?time SECOND SET ?second
Unix Timestamp
GET ?dt TIMESTAMP SET ?unix
AFTER EMIT ?unix

Formatting

FORMAT requires the explicit type keyword — DATE, TIME, or DATE AND TIME — followed by the variable and a format string with AS. Format tokens follow standard date formatting conventions.

Format Date, Time, and Datetime
NEW DATE SET ?date
AFTER NEW TIME SET ?time
AFTER NEW DATE AND TIME SET ?dt
AFTER FORMAT DATE ?date AS "d/m/Y" SET ?european
AFTER FORMAT TIME ?time AS "H:i" SET ?shorttime
AFTER FORMAT DATE AND TIME ?dt AS "Y-m-d H:i:s" SET ?formatted

Difference Between Two Dates

Subtracting two dates with AS [unit] returns the difference expressed in that unit. This works for days, hours, and years — enabling age calculations and duration comparisons.

Date Difference
NEW DATE SET ?date
AFTER NEW DATE FROM "2026-06-20" SET ?earlier
AFTER CALCULATE ?date - ?earlier AS days SET ?daysdiff
AFTER CALCULATE ?date - ?earlier AS hours SET ?hoursdiff
Age Calculation
NEW DATE SET ?date
AFTER NEW DATE FROM "1990-05-15" SET ?birthdate
AFTER CALCULATE ?date - ?birthdate AS years SET ?age
AFTER EMIT ?age

Timezone Conversion

CONVERT TIMEZONE converts a datetime to a target timezone using standard IANA timezone names.

Convert Timezone
NEW DATE AND TIME SET ?dt
AFTER CONVERT TIMEZONE ?dt TO "UTC" SET ?utc
AFTER CONVERT TIMEZONE ?dt TO "Africa/Johannesburg" SET ?jhb
AFTER CONVERT TIMEZONE ?dt TO "America/New_York" SET ?ny

Randomize Temporal Values

RANDOMIZE generates random dates, times, and datetimes within a specified range.

Random Date
RANDOMIZE DATE FROM RANGE "2020-01-01" TO "2025-12-31" SET ?randomdate
AFTER EMIT ?randomdate
Random Time
RANDOMIZE TIME FROM RANGE "09:00:00" TO "17:00:00" SET ?workhours
AFTER EMIT ?workhours
Random Datetime
RANDOMIZE DATE AND TIME FROM RANGE "2020-01-01 00:00:00" TO "2025-12-31 23:59:59" SET ?randomdt
AFTER EMIT ?randomdt
Arrays & Objects →