Temporal Expression APIs

All temporal operations are valid for both scalars and columns.

TemporalValue

Bases: Value

Functions

strftime(format_str)

Format timestamp according to format_str.

Format string may depend on the backend, but we try to conform to ANSI strftime.

Parameters:

Name	Type	Description	Default
format_str	str	strftime format string	required

Returns:

Type	Description
StringValue	Formatted version of arg

TimestampValue

Bases: _DateComponentMixin, _TimeComponentMixin, TemporalValue

Functions

__add__(other)

Add an interval to a timestamp.

__rsub__(other)

Subtract a timestamp or an interval from a timestamp.

__sub__(other)

Subtract a timestamp or an interval from a timestamp.

date()

Return the date component of the expression.

Returns:

Type	Description
DateValue	The date component of self

truncate(unit)

Truncate timestamp expression to units of unit.

Parameters:

Name	Type	Description	Default
unit	Literal['Y', 'Q', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns']	Unit to truncate to	required

Returns:

Type	Description
TimestampValue	Truncated timestamp expression

DateValue

Bases: TemporalValue, _DateComponentMixin

Functions

__add__(other)

Add an interval to a date.

__rsub__(other)

Subtract a date or an interval from a date.

__sub__(other)

Subtract a date or an interval from a date.

truncate(unit)

Truncate date expression to units of unit.

Parameters:

Name	Type	Description	Default
unit	Literal['Y', 'Q', 'M', 'W', 'D']	Unit to truncate arg to	required

Returns:

Type	Description
DateValue	Truncated date value expression

TimeValue

Bases: _TimeComponentMixin, TemporalValue

Functions

__add__(other)

Add an interval to a time expression.

__rsub__(other)

Subtract a time or an interval from a time expression.

__sub__(other)

Subtract a time or an interval from a time expression.

truncate(unit)

Truncate the expression to a time expression in units of unit.

Commonly used for time series resampling.

Parameters:

Name	Type	Description	Default
unit	Literal['h', 'm', 's', 'ms', 'us', 'ns']	The unit to truncate to	required

Returns:

Type	Description
TimeValue	self truncated to unit

IntervalValue

Bases: Value

Attributes

days: ir.IntegerValue property

Extract the number of days from an interval.

hours: ir.IntegerValue property

Extract the number of hours from an interval.

microseconds: ir.IntegerValue property

Extract the number of microseconds from an interval.

milliseconds: ir.IntegerValue property

Extract the number of milliseconds from an interval.

minutes: ir.IntegerValue property

Extract the number of minutes from an interval.

months: ir.IntegerValue property

Extract the number of months from an interval.

nanoseconds: ir.IntegerValue property

Extract the number of nanoseconds from an interval.

quarters: ir.IntegerValue property

Extract the number of quarters from an interval.

seconds: ir.IntegerValue property

Extract the number of seconds from an interval.

weeks: ir.IntegerValue property

Extract the number of weeks from an interval.

years: ir.IntegerValue property

Extract the number of years from an interval.

Functions

__add__(other)

Add this interval to other.

__floordiv__(other)

Floor-divide this interval by other.

__mul__(other)

Multiply this interval by other.

__rsub__(other)

Subtract other from this interval.

__sub__(other)

Subtract other from this interval.

negate()

Negate an interval expression.

Returns:

Type	Description
IntervalValue	A negated interval value expression

to_unit(target_unit)

Convert this interval to units of target_unit.

---

Last update: August 5, 2022