ReferenceSPQL

Date & Time

Construct, extract, and transform dates, times, timestamps, durations, and periods.

Scalar Functions

FunctionSummary
spql.dt.ceilCeil a temporal value to a fixed frequency in its local clock.
spql.dt.current_dateReturn the current UTC date.
spql.dt.current_timeReturn the current UTC time of day.
spql.dt.current_timestampReturn the current UTC timestamp.
spql.dt.dayExtract the calendar day of month.
spql.dt.day_of_weekExtract the zero-based weekday where Monday is 0.
spql.dt.day_of_yearExtract the one-based day of year.
spql.dt.duration_componentsSplit a duration into day-time components.
spql.dt.duration_totalReturn a duration total in the requested unit.
spql.dt.floorFloor a temporal value to a fixed frequency in its local clock.
spql.dt.formatFormat local calendar fields with a strftime-like pattern.
spql.dt.from_epochConvert an epoch count into a timestamp in the requested unit.
spql.dt.hourExtract the hour of day.
spql.dt.is_leap_yearReturn whether the date belongs to a leap year.
spql.dt.is_month_endReturn whether the date is the last day of its month.
spql.dt.is_month_startReturn whether the date is the first day of its month.
spql.dt.is_quarter_endReturn whether the date ends a quarter.
spql.dt.is_quarter_startReturn whether the date starts a quarter.
spql.dt.is_year_endReturn whether the date ends a year.
spql.dt.is_year_startReturn whether the date starts a year.
spql.dt.iso_dayExtract the ISO weekday where Monday is 1.
spql.dt.iso_weekExtract the ISO week number.
spql.dt.iso_yearExtract the ISO week-numbering year.
spql.dt.local_timeReturn the current local time of day.
spql.dt.local_timestampReturn the current local timestamp.
spql.dt.minuteExtract the minute of hour.
spql.dt.monthExtract the calendar month.
spql.dt.parse_dateParse text as a calendar date.
spql.dt.parse_durationParse a fixed elapsed duration.
spql.dt.parse_periodParse text as a regular calendar period.
spql.dt.parse_timeParse text as a time of day.
spql.dt.parse_timestampParse text as a timestamp.
spql.dt.period_boundsReturn half-open date bounds for a period string.
spql.dt.period_endReturn the exclusive end date of a period.
spql.dt.period_startReturn the inclusive start date of a period.
spql.dt.quarterExtract the calendar quarter.
spql.dt.roundRound a temporal value to a fixed frequency in its local clock.
spql.dt.secondExtract the second of minute.
spql.dt.to_dateConvert a timestamp's local date or a period to a calendar date.
spql.dt.to_durationConvert a time of day to an elapsed duration since midnight.
spql.dt.to_epochConvert a temporal value into an epoch count.
spql.dt.to_periodConvert a date, local timestamp, or period to a regular calendar period.
spql.dt.to_timeConvert a timestamp to its local time of day.
spql.dt.to_timestampConvert a date or period to a timestamp at midnight.
spql.dt.truncTruncate a temporal value to a local calendar or clock part.
spql.dt.tz_convertChange an already-zoned timestamp to another timezone, preserving its instant and unit.
spql.dt.tz_localizeLocalize civil timestamps, preserving units. Reject skipped and, by default, repeated times.
spql.dt.yearExtract the calendar year.

spql.dt.ceil

Ceil a temporal value to a fixed frequency in its local clock.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.ceil(value, 'freq') -> inferred

The result type and nullability are inferred from the argument types when the call is bound.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.DurationTemporal value to inspect, convert or format.
freqyesutf8?Bind-time fixed frequency.

spql.dt.current_date

Return the current UTC date.

  • Kind: scalar function
  • Volatility: volatile
spql.dt.current_date() -> vortex.date

The system clock is sampled once per input batch. Values may differ between batches and between executions of a reused plan.

Parameters

No parameters.

spql.dt.current_time

Return the current UTC time of day.

  • Kind: scalar function
  • Volatility: volatile
spql.dt.current_time() -> vortex.time

The system clock is sampled once per input batch. Values may differ between batches and between executions of a reused plan.

Parameters

No parameters.

spql.dt.current_timestamp

Return the current UTC timestamp.

  • Kind: scalar function
  • Volatility: volatile
spql.dt.current_timestamp() -> vortex.timestamp

The system clock is sampled once per input batch. Values may differ between batches and between executions of a reused plan.

Parameters

No parameters.

spql.dt.day

Extract the calendar day of month.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.day(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.day_of_week

Extract the zero-based weekday where Monday is 0.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.day_of_week(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.day_of_year

Extract the one-based day of year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.day_of_year(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.duration_components

Split a duration into day-time components.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.duration_components(value) -> struct { days: i64?, hours: i64?, minutes: i64?, seconds: i64?, nanoseconds: i64? }?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesspql.DurationTemporal value to inspect, convert or format.

spql.dt.duration_total

Return a duration total in the requested unit.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.duration_total(value, 'unit') -> i64?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesspql.DurationTemporal value to inspect, convert or format.
unityesutf8?Bind-time output unit.

spql.dt.floor

Floor a temporal value to a fixed frequency in its local clock.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.floor(value, 'freq') -> inferred

The result type and nullability are inferred from the argument types when the call is bound.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.DurationTemporal value to inspect, convert or format.
freqyesutf8?Bind-time fixed frequency.

spql.dt.format

Format local calendar fields with a strftime-like pattern.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.format(value, 'format') -> utf8?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.Duration | spql.PeriodTemporal value to inspect, convert or format.
formatyesutf8?Bind-time strftime-like pattern.

spql.dt.from_epoch

Convert an epoch count into a timestamp in the requested unit.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.from_epoch(value, 'unit') -> vortex.timestamp?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Parameters

NameRequiredTypeDescription
valueyesi64?Signed epoch offset in the selected unit.
unityesutf8?Bind-time timestamp unit: s, ms, us, or ns.

Returns

A timestamp that uses the requested unit.

spql.dt.hour

Extract the hour of day.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.hour(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.time | vortex.timestampTemporal value to inspect, convert or format.

spql.dt.is_leap_year

Return whether the date belongs to a leap year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_leap_year(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_month_end

Return whether the date is the last day of its month.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_month_end(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_month_start

Return whether the date is the first day of its month.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_month_start(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_quarter_end

Return whether the date ends a quarter.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_quarter_end(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_quarter_start

Return whether the date starts a quarter.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_quarter_start(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_year_end

Return whether the date ends a year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_year_end(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.is_year_start

Return whether the date starts a year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.is_year_start(value) -> bool?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.iso_day

Extract the ISO weekday where Monday is 1.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.iso_day(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.iso_week

Extract the ISO week number.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.iso_week(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.iso_year

Extract the ISO week-numbering year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.iso_year(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.local_time

Return the current local time of day.

  • Kind: scalar function
  • Volatility: volatile
spql.dt.local_time() -> vortex.time

The system clock is sampled once per input batch. Values may differ between batches and between executions of a reused plan.

Parameters

No parameters.

spql.dt.local_timestamp

Return the current local timestamp.

  • Kind: scalar function
  • Volatility: volatile
spql.dt.local_timestamp() -> vortex.timestamp

The system clock is sampled once per input batch. Values may differ between batches and between executions of a reused plan.

Parameters

No parameters.

spql.dt.minute

Extract the minute of hour.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.minute(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.time | vortex.timestampTemporal value to inspect, convert or format.

spql.dt.month

Extract the calendar month.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.month(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.parse_date

Parse text as a calendar date.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.parse_date(value, 'format'?, 'errors'?) -> vortex.date?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Null inputs propagate. Coercion handles value errors only. Invalid controls fail binding. Dates use days; times and zone-free timestamps use nanoseconds.

Parameters

NameRequiredTypeDescription
valueyesutf8?Text to parse.
formatnoutf8?Numeric pattern: %Y, %m, %d, %j, %H, %M, %S, %f, %%. Timezones unsupported.
errorsnoutf8?Error policy: raise (default) or coerce (invalid or overflowing values become null).

spql.dt.parse_duration

Parse a fixed elapsed duration.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.parse_duration(value) -> spql.Duration?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesutf8?Duration text such as 2h or 1500ms.

spql.dt.parse_period

Parse text as a regular calendar period.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.parse_period(value, 'freq') -> spql.Period?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Parameters

NameRequiredTypeDescription
valueyesutf8?A date or frequency-appropriate period label.
freqyesutf8?Bind-time period frequency: D, W, MS, ME, QS, QE, YS, or YE.

spql.dt.parse_time

Parse text as a time of day.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.parse_time(value, 'format'?, 'errors'?) -> vortex.time?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Null inputs propagate. Coercion handles value errors only. Invalid controls fail binding. Dates use days; times and zone-free timestamps use nanoseconds.

Parameters

NameRequiredTypeDescription
valueyesutf8?Text to parse.
formatnoutf8?Numeric pattern: %Y, %m, %d, %j, %H, %M, %S, %f, %%. Timezones unsupported.
errorsnoutf8?Error policy: raise (default) or coerce (invalid or overflowing values become null).

spql.dt.parse_timestamp

Parse text as a timestamp.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.parse_timestamp(value, 'format'?, 'errors'?) -> vortex.timestamp?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Null inputs propagate. Coercion handles value errors only. Invalid controls fail binding. Dates use days; times and zone-free timestamps use nanoseconds.

Parameters

NameRequiredTypeDescription
valueyesutf8?Text to parse.
formatnoutf8?Numeric pattern: %Y, %m, %d, %j, %H, %M, %S, %f, %%. Timezones unsupported.
errorsnoutf8?Error policy: raise (default) or coerce (invalid or overflowing values become null).

spql.dt.period_bounds

Return half-open date bounds for a period string.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.period_bounds(value, 'freq') -> struct { start: vortex.date?, end: vortex.date? }?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesutf8?Text to parse as a temporal value.
freqyesutf8?Bind-time period frequency.

spql.dt.period_end

Return the exclusive end date of a period.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.period_end(value) -> vortex.date?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesspql.PeriodTemporal value to inspect, convert or format.

spql.dt.period_start

Return the inclusive start date of a period.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.period_start(value) -> vortex.date?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesspql.PeriodTemporal value to inspect, convert or format.

spql.dt.quarter

Extract the calendar quarter.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.quarter(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.round

Round a temporal value to a fixed frequency in its local clock.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.round(value, 'freq') -> inferred

The result type and nullability are inferred from the argument types when the call is bound.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.DurationTemporal value to inspect, convert or format.
freqyesutf8?Bind-time fixed frequency.

spql.dt.second

Extract the second of minute.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.second(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.time | vortex.timestampTemporal value to inspect, convert or format.

spql.dt.to_date

Convert a timestamp's local date or a period to a calendar date.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_date(value) -> type(value)

Same type and nullability as value.

Parameters

NameRequiredTypeDescription
valueyesvortex.dateTemporal value to inspect, convert or format.
spql.dt.to_date(value) -> vortex.date?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.to_duration

Convert a time of day to an elapsed duration since midnight.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_duration(value) -> type(value)

Same type and nullability as value.

Parameters

NameRequiredTypeDescription
valueyesspql.DurationTemporal value to inspect, convert or format.
spql.dt.to_duration(value) -> spql.Duration?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.timeTemporal value to inspect, convert or format.

spql.dt.to_epoch

Convert a temporal value into an epoch count.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_epoch(value, 'unit') -> i64?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.DurationTemporal value to inspect, convert or format.
unityesutf8?Bind-time output unit.

spql.dt.to_period

Convert a date, local timestamp, or period to a regular calendar period.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_period(value, 'freq') -> spql.Period?

Nullable when an argument is nullable; otherwise non-nullable. Literal arguments can refine the result type, including its units, shape or element type.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.
freqyesutf8?Bind-time period frequency: D, W, MS, ME, QS, QE, YS, or YE.

spql.dt.to_time

Convert a timestamp to its local time of day.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_time(value) -> type(value)

Same type and nullability as value.

Parameters

NameRequiredTypeDescription
valueyesvortex.timeTemporal value to inspect, convert or format.
spql.dt.to_time(value) -> vortex.time?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.timestampTemporal value to inspect, convert or format.

spql.dt.to_timestamp

Convert a date or period to a timestamp at midnight.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.to_timestamp(value) -> type(value)

Same type and nullability as value.

Parameters

NameRequiredTypeDescription
valueyesvortex.timestampTemporal value to inspect, convert or format.
spql.dt.to_timestamp(value) -> vortex.timestamp?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | spql.PeriodTemporal value to inspect, convert or format.

spql.dt.trunc

Truncate a temporal value to a local calendar or clock part.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.trunc(value, 'part') -> inferred

The result type and nullability are inferred from the argument types when the call is bound.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.time | vortex.timestamp | spql.DurationTemporal value to inspect, convert or format.
partyesutf8?Bind-time temporal part.

spql.dt.tz_convert

Change an already-zoned timestamp to another timezone, preserving its instant and unit.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.tz_convert(value, 'zone') -> inferred

The result type and nullability are inferred from the argument types when the call is bound. Literal arguments can refine the result type, including its units, shape or element type.

Parameters

NameRequiredTypeDescription
valueyesvortex.timestampTemporal value to inspect, convert or format.
zoneyesutf8?Bind-time timezone name.

spql.dt.tz_localize

Localize civil timestamps, preserving units. Reject skipped and, by default, repeated times.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.tz_localize(value, 'zone', 'ambiguous'?, 'nonexistent'?) -> inferred

The result type and nullability are inferred from the argument types when the call is bound. Literal arguments can refine the result type, including its units, shape or element type.

Parameters

NameRequiredTypeDescription
valueyesvortex.timestampTemporal value to inspect, convert or format.
zoneyesutf8?Bind-time timezone name.
ambiguousnoutf8?Repeated-time policy: raise (default), earliest, or latest.
nonexistentnoutf8?Skipped-time policy: raise (default). Other policies are rejected.

spql.dt.year

Extract the calendar year.

  • Kind: scalar function
  • Volatility: immutable
spql.dt.year(value) -> i32?

Nullable when an argument is nullable; otherwise non-nullable.

Parameters

NameRequiredTypeDescription
valueyesvortex.date | vortex.timestamp | spql.PeriodTemporal value to inspect, convert or format.
Found a problem? Edit this page or report an issue.

On this page