Date/Time Functions¶

Functions for parsing, formatting, and calculating with dates and times.

Summary¶

Function	Signature	Description
`business_days_between`	`number, number -> number`	Count business days (weekdays) between two timestamps
`date_add`	`number, number, string -> number`	Add time to timestamp
`date_diff`	`number, number, string -> number`	Difference between timestamps
`duration_since`	`number\\|string -> object`	Get detailed duration object from timestamp to now
`end_of_day`	`number\\|string -> string`	Get ISO 8601 string for end of day (23:59:59)
`epoch_ms`	`-> number`	Current Unix timestamp in milliseconds (alias for now_ms)
`format_date`	`number, string -> string`	Format timestamp to string
`from_epoch`	`number -> string`	Convert Unix timestamp (seconds) to ISO 8601 string
`from_epoch_ms`	`number -> string`	Convert Unix timestamp (milliseconds) to ISO 8601 string
`is_after`	`number\\|string, number\\|string -> boolean`	Check if first date is after second date (accepts timestamps or date strings)
`is_before`	`number\\|string, number\\|string -> boolean`	Check if first date is before second date (accepts timestamps or date strings)
`is_between`	`number\\|string, number\\|string, number\\|string -> boolean`	Check if date is between start and end (inclusive, accepts timestamps or date strings)
`is_same_day`	`number\\|string, number\\|string -> boolean`	Check if two timestamps/dates are on the same day
`is_weekday`	`number -> boolean`	Check if timestamp falls on weekday (Monday-Friday)
`is_weekend`	`number -> boolean`	Check if timestamp falls on weekend (Saturday or Sunday)
`parse_date`	`string, string? -> number`	Parse date string to timestamp
`parse_datetime`	`string -> string \\| null`	Parse structured date/time string to ISO 8601 UTC
`parse_natural_date`	`string -> string \\| null`	Parse natural language date expression to ISO 8601 UTC (relative to now)
`quarter`	`number -> number`	Get quarter of year (1-4) from timestamp
`relative_time`	`number -> string`	Human-readable relative time from timestamp
`start_of_day`	`number\\|string -> string`	Get ISO 8601 string for start of day (00:00:00)
`start_of_month`	`number\\|string -> string`	Get ISO 8601 string for start of month
`start_of_week`	`number\\|string -> string`	Get ISO 8601 string for start of week (Monday 00:00:00)
`start_of_year`	`number\\|string -> string`	Get ISO 8601 string for start of year
`time_ago`	`number\\|string -> string`	Human-readable time since date (accepts timestamps or date strings)
`timezone_convert`	`string, string, string -> string`	Convert timestamp between timezones (IANA timezone names)
`to_epoch`	`number\\|string -> number`	Convert date string or timestamp to Unix timestamp (seconds)
`to_epoch_ms`	`number\\|string -> number`	Convert date string or timestamp to Unix timestamp (milliseconds)

Functions¶

business_days_between¶

Count business days (weekdays) between two timestamps

Signature: number, number -> number

Examples:

# Count weekdays
business_days_between(`1704067200`, `1705276800`) -> 10
# Between two timestamps
business_days_between(start_ts, end_ts) -> count
# One week = 5 days
business_days_between(`0`, `604800`) -> 5
# Same day
business_days_between(`0`, `0`) -> 0

date_add¶

Add time to timestamp

Signature: number, number, string -> number

Examples:

# Add 1 day
date_add(`0`, `1`, 'days') -> 86400
# Add 2 hours
date_add(`0`, `2`, 'hours') -> 7200
# Add 1 week
date_add(timestamp, `7`, 'days') -> next week
# Add 30 minutes
date_add(`0`, `30`, 'minutes') -> 1800

date_diff¶

Difference between timestamps

Signature: number, number, string -> number

Examples:

# Diff in days
date_diff(`86400`, `0`, 'days') -> 1
# Diff in hours
date_diff(`7200`, `0`, 'hours') -> 2
# Diff in minutes
date_diff(end_ts, start_ts, 'minutes') -> minutes
# Diff in weeks
date_diff(`604800`, `0`, 'weeks') -> 1

duration_since¶

Get detailed duration object from timestamp to now

Signature: number|string -> object

Examples:

# From timestamp
duration_since(`1702396800`) -> {days: 1, hours: 0, ...}
# From date string
duration_since('2023-01-01') -> {days: N, ...}
# Time since creation
duration_since(created_at) -> elapsed time
# One hour ago
duration_since(now() - 3600) -> {hours: 1, ...}

end_of_day¶

Get ISO 8601 string for end of day (23:59:59)

Signature: number|string -> string

Examples:

# From ISO string
end_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T23:59:59Z\"
# From timestamp
end_of_day(`1702483200`) -> end of that day
# From date only
end_of_day('2024-01-01') -> last second of day
# End of today
end_of_day(now()) -> today end

epoch_ms¶

Current Unix timestamp in milliseconds (alias for now_ms)

Signature: -> number

Examples:

# Current time in ms
epoch_ms() -> 1702483200000
# Convert to seconds
epoch_ms() / `1000` -> seconds
# Calculate duration
epoch_ms() - start_ms -> elapsed

format_date¶

Format timestamp to string

Signature: number, string -> string

Examples:

# ISO date format
format_date(`1705276800`, '%Y-%m-%d') -> \"2024-01-15\"
# Long date format
format_date(ts, '%B %d, %Y') -> \"January 15, 2024\"
# Time only
format_date(ts, '%H:%M:%S') -> \"10:30:00\"
# Full ISO 8601
format_date(ts, '%Y-%m-%dT%H:%M:%SZ') -> ISO string

from_epoch¶

Convert Unix timestamp (seconds) to ISO 8601 string

Signature: number -> string

Examples:

# Convert seconds
from_epoch(`1702483200`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch(`0`) -> \"1970-01-01T00:00:00Z\"
# Convert field
from_epoch(created_at) -> ISO string
# Current time
from_epoch(now()) -> current ISO

from_epoch_ms¶

Convert Unix timestamp (milliseconds) to ISO 8601 string

Signature: number -> string

Examples:

# From milliseconds
from_epoch_ms(`1702483200000`) -> \"2023-12-13T16:00:00Z\"
# Unix epoch
from_epoch_ms(`0`) -> \"1970-01-01T00:00:00Z\"
# JS timestamp
from_epoch_ms(js_timestamp) -> ISO
# Current time
from_epoch_ms(epoch_ms()) -> current

is_after¶

Check if first date is after second date (accepts timestamps or date strings)

Signature: number|string, number|string -> boolean

Examples:

# String comparison
is_after('2024-07-15', '2024-01-01') -> true
# Timestamp comparison
is_after(`1705276800`, `1704067200`) -> true
# Field comparison
is_after(end_date, start_date) -> true/false
# Same date
is_after('2024-01-01', '2024-01-01') -> false

is_before¶

Check if first date is before second date (accepts timestamps or date strings)

Signature: number|string, number|string -> boolean

Examples:

# String comparison
is_before('2024-01-01', '2024-07-15') -> true
# Timestamp comparison
is_before(`1704067200`, `1705276800`) -> true
# Field comparison
is_before(start_date, end_date) -> true/false
# Same date
is_before('2024-01-01', '2024-01-01') -> false

is_between¶

Check if date is between start and end (inclusive, accepts timestamps or date strings)

Signature: number|string, number|string, number|string -> boolean

Examples:

# Within range
is_between('2024-06-15', '2024-01-01', '2024-12-31') -> true
# Before range
is_between('2023-06-15', '2024-01-01', '2024-12-31') -> false
# Check event date
is_between(event_date, start, end) -> true/false
# Inclusive start
is_between('2024-01-01', '2024-01-01', '2024-12-31') -> true

is_same_day¶

Check if two timestamps/dates are on the same day

Signature: number|string, number|string -> boolean

Examples:

# Same day, different time
is_same_day('2023-12-13T10:00:00Z', '2023-12-13T23:00:00Z') -> true
# Different days
is_same_day('2023-12-13', '2023-12-14') -> false
# Compare fields
is_same_day(created_at, updated_at) -> true/false
# Today check
is_same_day(now(), event_time) -> true/false

is_weekday¶

Check if timestamp falls on weekday (Monday-Friday)

Signature: number -> boolean

Examples:

# Monday is weekday
is_weekday(`1705276800`) -> true
# Check current day
is_weekday(now()) -> true/false
# Check event day
is_weekday(event_timestamp) -> true/false
# Saturday is not weekday
is_weekday(`1705104000`) -> false

is_weekend¶

Check if timestamp falls on weekend (Saturday or Sunday)

Signature: number -> boolean

Examples:

# Saturday is weekend
is_weekend(`1705104000`) -> true
# Check current day
is_weekend(now()) -> true/false
# Monday is not weekend
is_weekend(`1705276800`) -> false
# Check event day
is_weekend(event_timestamp) -> true/false

parse_date¶

Parse date string to timestamp

Signature: string, string? -> number

Examples:

# ISO date format
parse_date('2024-01-15', '%Y-%m-%d') -> 1705276800
# US date format
parse_date('01/15/2024', '%m/%d/%Y') -> timestamp
# Named month
parse_date('15-Jan-2024', '%d-%b-%Y') -> timestamp
# With time
parse_date('2024-01-15T10:30:00', '%Y-%m-%dT%H:%M:%S') -> timestamp

parse_datetime¶

Parse structured date/time string to ISO 8601 UTC

Signature: string -> string | null

Examples:

# ISO date
parse_datetime("2024-01-15") -> "2024-01-15T00:00:00Z"
# ISO datetime
parse_datetime("2024-01-15T10:30:00Z") -> "2024-01-15T10:30:00Z"
# Human date
parse_datetime("Jan 15, 2024") -> "2024-01-15T00:00:00Z"
# US date format
parse_datetime("01/15/2024") -> "2024-01-15T00:00:00Z"
# Unix timestamp
parse_datetime("1705363200") -> "2024-01-16T00:00:00Z"
# Returns null for unparseable
parse_datetime("invalid") -> null

parse_natural_date¶

Parse natural language date expression to ISO 8601 UTC (relative to now)

Signature: string -> string | null

Examples:

# Yesterday
parse_natural_date("yesterday") -> "2026-01-25T00:00:00Z"
# Tomorrow
parse_natural_date("tomorrow") -> "2026-01-27T00:00:00Z"
# Relative past
parse_natural_date("3 days ago") -> "2026-01-23T00:00:00Z"
# Next weekday
parse_natural_date("next friday") -> "2026-01-31T00:00:00Z"
# Weeks ago
parse_natural_date("2 weeks ago") -> "2026-01-12T00:00:00Z"
# Returns null for unparseable
parse_natural_date("invalid") -> null

quarter¶

Get quarter of year (1-4) from timestamp

Signature: number -> number

Examples:

# April is Q2
quarter(`1713139200`) -> 2
# January is Q1
quarter(`1704067200`) -> 1
# July is Q3
quarter(`1719792000`) -> 3
# November is Q4
quarter(`1730419200`) -> 4

relative_time¶

Human-readable relative time from timestamp

Signature: number -> string

Examples:

# One hour ago
relative_time(now() - 3600) -> \"1 hour ago\"
# One minute ago
relative_time(now() - 60) -> \"1 minute ago\"
# One day ago
relative_time(now() - 86400) -> \"1 day ago\"
# From field
relative_time(created_at) -> human readable

start_of_day¶

Get ISO 8601 string for start of day (00:00:00)

Signature: number|string -> string

Examples:

# From ISO string
start_of_day('2023-12-13T15:30:00Z') -> \"2023-12-13T00:00:00Z\"
# From timestamp
start_of_day(`1702483200`) -> start of that day
# Today start
start_of_day(now()) -> today midnight
# From date only
start_of_day('2024-01-15') -> midnight

start_of_month¶

Get ISO 8601 string for start of month

Signature: number|string -> string

Examples:

# From ISO string
start_of_month('2023-12-13T15:30:00Z') -> \"2023-12-01T00:00:00Z\"
# Current month start
start_of_month(now()) -> first of month
# From timestamp
start_of_month(`1702483200`) -> month start
# March start
start_of_month('2024-03-15') -> \"2024-03-01T00:00:00Z\"

start_of_week¶

Get ISO 8601 string for start of week (Monday 00:00:00)

Signature: number|string -> string

Examples:

# Wednesday to Monday
start_of_week('2023-12-13T15:30:00Z') -> \"2023-12-11T00:00:00Z\"
# Current week start
start_of_week(now()) -> this Monday
# From timestamp
start_of_week(`1702483200`) -> week start
# Monday stays Monday
start_of_week('2024-01-15') -> \"2024-01-15T00:00:00Z\"

start_of_year¶

Get ISO 8601 string for start of year

Signature: number|string -> string

Examples:

# From ISO string
start_of_year('2023-12-13T15:30:00Z') -> \"2023-01-01T00:00:00Z\"
# Current year start
start_of_year(now()) -> Jan 1st
# From timestamp
start_of_year(`1702483200`) -> year start
# Mid-year to Jan 1
start_of_year('2024-06-15') -> \"2024-01-01T00:00:00Z\"

time_ago¶

Human-readable time since date (accepts timestamps or date strings)

Signature: number|string -> string

Examples:

# From date string
time_ago('2020-01-01') -> \"4 years ago\"
# One hour ago
time_ago(now() - 3600) -> \"1 hour ago\"
# From field
time_ago(created_at) -> human readable
# Months ago
time_ago('2023-12-01') -> \"X months ago\"

timezone_convert¶

Convert timestamp between timezones (IANA timezone names)

Signature: string, string, string -> string

Examples:

# NY to London
timezone_convert('2024-01-15T10:00:00', 'America/New_York', 'Europe/London') -> \"2024-01-15T15:00:00\"
# UTC to Pacific
timezone_convert(time, 'UTC', 'America/Los_Angeles') -> PST time
# Tokyo to UTC
timezone_convert(time, 'Asia/Tokyo', 'UTC') -> UTC time
# Paris to Chicago
timezone_convert(time, 'Europe/Paris', 'America/Chicago') -> CST time

to_epoch¶

Convert date string or timestamp to Unix timestamp (seconds)

Signature: number|string -> number

Examples:

# From ISO string
to_epoch('2023-12-13T16:00:00Z') -> 1702483200
# From date only
to_epoch('2024-01-01') -> timestamp
# Convert field
to_epoch(date_field) -> seconds
# Unix epoch
to_epoch('1970-01-01T00:00:00Z') -> 0

to_epoch_ms¶

Convert date string or timestamp to Unix timestamp (milliseconds)

Signature: number|string -> number

Examples:

# From ISO string
to_epoch_ms('2023-12-13T16:00:00Z') -> 1702483200000
# From date only
to_epoch_ms('2024-01-01') -> timestamp_ms
# Convert field
to_epoch_ms(date_field) -> milliseconds
# Unix epoch
to_epoch_ms('1970-01-01T00:00:00Z') -> 0