ExprDateTimeNameSpace

class

class ExprDateTimeNameSpace

Categories: date

Date and time methods, accessed via Expr.dt.

Examples

tf.with_columns(col("ts").dt.year().alias("year"))

Methods

method

add_business_days

def add_business_days(
    n: int | IntoExpr,
    *,
    week_mask: Iterable[bool] = (True, True, True, True, True, False, False),
    holidays: Iterable[Any] | Expr = (),
    roll: Roll = 'raise',
) -> Expr

Shift a date or datetime by n business days.

Parameters:

parameter

nint | IntoExpr (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None)

Number of business days to add; negative subtracts.

parameter

week_maskIterable[bool]

Seven booleans, Monday to Sunday, marking which weekdays count as business days.

parameter

holidaysIterable[Any] | Expr

Dates to skip in addition to non-business weekdays.

parameter

rollRoll (Literal['raise', 'forward', 'backward'])

How to handle a non-business start date: raise, forward or backward.

Example:

tf.with_columns(col("d").dt.add_business_days(3).alias("due"))

A start date that is not a business day raises unless roll says which way to move it first:

tf.with_columns(col("d").dt.add_business_days(3, roll="forward"))

method

truncate

def truncate(every: str | Expr) -> Expr

Truncate each datetime down to a multiple of an interval.

Parameters:

parameter

everystr | Expr

Interval to truncate to, e.g. 1mo, 1w, 1d, 1h or 15m.

Example:

col("ts").dt.truncate("1mo")  # -> first day of the month

method

replace

def replace(
    *,
    year: int | IntoExpr | None = None,
    month: int | IntoExpr | None = None,
    day: int | IntoExpr | None = None,
    hour: int | IntoExpr | None = None,
    minute: int | IntoExpr | None = None,
    second: int | IntoExpr | None = None,
    microsecond: int | IntoExpr | None = None,
    ambiguous: Ambiguous | Expr = 'raise',
) -> Expr

Replace individual date or time components with new values.

Each component left as None is kept unchanged.

Parameters:

parameter

yearint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New year value.

parameter

monthint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New month value (1 to 12).

parameter

dayint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New day of month (1 to 31).

parameter

hourint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New hour (0 to 23).

parameter

minuteint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New minute (0 to 59).

parameter

secondint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New second (0 to 59).

parameter

microsecondint | IntoExpr | None (int | int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | str | None | None)

New microsecond.

parameter

ambiguousAmbiguous | Expr (Literal['earliest', 'latest', 'raise', 'null'] | Expr)

Policy for ambiguous local times: earliest, latest, raise or null.

Example:

tf.select(col("ts").dt.replace(day=1).alias("first_of_month"))

method

combine

def combine(time: Expr, time_unit: TimeUnit = 'us') -> Expr

Combine the date part with a time into a datetime.

Parameters:

parameter

timeExpr

Time or expression to attach to each date.

parameter

time_unitTimeUnit (Literal['ns', 'us', 'ms'])

Resolution of the result: ns, us or ms.

Example:

tf.select(col("ts").dt.combine(time(9, 0)).alias("opening"))

method

to_string

def to_string(format: str | None = None) -> Expr

Format each temporal value as a string.

Parameters:

parameter

formatstr | None

chrono-style format string (e.g. %Y-%m-%d); defaults to ISO 8601 when omitted.

Example:

tf.select(col("ts").dt.to_string("%Y-%m-%d").alias("day"))

method

strftime

def strftime(format: str) -> Expr

Format each temporal value as a string using format.

Parameters:

parameter

formatstr

chrono-style format string, e.g. %Y-%m-%d %H:%M:%S.

Example:

tf.select(col("ts").dt.strftime("%H:%M").alias("clock"))

method

millennium

def millennium() -> Expr

Extract the millennium of each date.

Example:

tf.select(col("d").dt.millennium().alias("millennium"))

method

century

def century() -> Expr

Extract the century of each date.

Example:

tf.select(col("d").dt.century().alias("century"))

method

year

def year() -> Expr

Extract the year of each date.

Example:

tf.group_by(col("d").dt.year().alias("year")).len()

method

is_leap_year

def is_leap_year() -> Expr

Return whether each year is a leap year.

Example:

tf.filter(col("d").dt.is_leap_year())

method

iso_year

def iso_year() -> Expr

Extract the ISO 8601 year of each date.

Example:

tf.select(col("d").dt.iso_year().alias("iso_year"))

method

quarter

def quarter() -> Expr

Extract the quarter of each date (1 to 4).

Example:

tf.group_by(col("d").dt.quarter().alias("quarter")).len()

method

month

def month() -> Expr

Extract the month of each date (1 to 12).

Example:

tf.select(col("d").dt.month().alias("month"))

method

week

def week() -> Expr

Extract the ISO 8601 week number of each date (1 to 53).

Example:

tf.select(col("d").dt.week().alias("week"))

method

weekday

def weekday() -> Expr

Extract the ISO weekday (1 for Monday to 7 for Sunday).

Example:

tf.filter(col("d").dt.weekday() <= 5)  # weekdays only

method

day

def day() -> Expr

Extract the day of the month (1 to 31).

Example:

tf.select(col("d").dt.day().alias("day"))

method

ordinal_day

def ordinal_day() -> Expr

Extract the day of the year (1 to 366).

Example:

tf.select(col("d").dt.ordinal_day().alias("day_of_year"))

method

time

def time() -> Expr

Extract the time component of each datetime.

Example:

tf.select(col("ts").dt.time().alias("time"))

method

date

def date() -> Expr

Extract the date component of each datetime.

Example:

tf.select(col("ts").dt.date().alias("date"))

method

datetime

def datetime() -> Expr

Extract the datetime value.

Example:

tf.select(col("ts").dt.datetime().alias("moment"))

method

hour

def hour() -> Expr

Extract the hour of each datetime (0 to 23).

Example:

tf.filter(col("ts").dt.hour() >= 12)  # afternoon rows

method

minute

def minute() -> Expr

Extract the minute of each datetime (0 to 59).

Example:

tf.select(col("ts").dt.minute().alias("minute"))

method

second

def second(*, fractional: bool = False) -> Expr

Extract the second of each datetime (0 to 59).

Parameters:

parameter

fractionalbool

If True, include the sub-second fraction.

Example:

tf.select(col("ts").dt.second().alias("second"))

fractional=True folds the sub-second part into the result:

tf.select(col("ts").dt.second(fractional=True).alias("second"))

method

millisecond

def millisecond() -> Expr

Extract the millisecond of each datetime.

Example:

tf.select(col("ts").dt.millisecond().alias("ms"))

method

microsecond

def microsecond() -> Expr

Extract the microsecond of each datetime.

Example:

tf.select(col("ts").dt.microsecond().alias("us"))

method

nanosecond

def nanosecond() -> Expr

Extract the nanosecond of each datetime.

Example:

tf.select(col("ts").dt.nanosecond().alias("ns"))

method

epoch

def epoch(time_unit: EpochTimeUnit = 'us') -> Expr

Return time since the Unix epoch in the given unit.

Parameters:

parameter

time_unitEpochTimeUnit (Literal['ns', 'us', 'ms', 's', 'd'])

Output unit: ns, us, ms, s or d.

Example:

tf.select(col("ts").dt.epoch("s").alias("unix_seconds"))

method

timestamp

def timestamp(time_unit: TimeUnit = 'us') -> Expr

Return the timestamp of each datetime in the given unit.

Parameters:

parameter

time_unitTimeUnit (Literal['ns', 'us', 'ms'])

Output unit: ns, us or ms.

Example:

tf.select(col("ts").dt.timestamp("ms").alias("stamp"))

method

with_time_unit

def with_time_unit(time_unit: TimeUnit) -> Expr

Relabel the time unit without changing the stored values.

Parameters:

parameter

time_unitTimeUnit (Literal['ns', 'us', 'ms'])

New unit: ns, us or ms.

Example:

tf.select(col("ts").dt.with_time_unit("ms"))

This relabels the unit and therefore reinterprets the stored numbers; use cast_time_unit to keep the same instant:

tf.select(col("ts").dt.cast_time_unit("ms"))

method

cast_time_unit

def cast_time_unit(time_unit: TimeUnit) -> Expr

Cast to a different time unit, converting the values.

Parameters:

parameter

time_unitTimeUnit (Literal['ns', 'us', 'ms'])

Target unit: ns, us or ms.

Example:

tf.select(col("ts").dt.cast_time_unit("ms"))

method

convert_time_zone

def convert_time_zone(time_zone: str) -> Expr

Convert to another time zone, keeping the same instant.

Parameters:

parameter

time_zonestr

Target IANA time zone, e.g. America/New_York.

Example:

tf.select(
    col("ts")
    .dt.replace_time_zone("UTC")
    .dt.convert_time_zone("Europe/Madrid")
)

method

replace_time_zone

def replace_time_zone(
    time_zone: str | None,
    *,
    ambiguous: Ambiguous | Expr = 'raise',
    non_existent: NonExistent = 'raise',
) -> Expr

Set the time zone without shifting the instant.

Parameters:

parameter

time_zonestr | None

Target IANA time zone, or None to make the value time-zone-naive.

parameter

ambiguousAmbiguous | Expr (Literal['earliest', 'latest', 'raise', 'null'] | Expr)

Policy for ambiguous local times: earliest, latest, raise or null.

parameter

non_existentNonExistent (Literal['raise', 'null'])

Policy for non-existent local times: raise or null.

Example:

tf.with_columns(col("ts").dt.replace_time_zone("UTC"))

method

total_days

def total_days(*, fractional: bool = False) -> Expr

Total number of days in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_days().alias("days"))

method

total_hours

def total_hours(*, fractional: bool = False) -> Expr

Total number of hours in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_hours().alias("hours"))

method

total_minutes

def total_minutes(*, fractional: bool = False) -> Expr

Total number of minutes in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_minutes().alias("minutes"))

method

total_seconds

def total_seconds(*, fractional: bool = False) -> Expr

Total number of seconds in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_seconds().alias("seconds"))

fractional=True keeps the remainder instead of truncating:

tf.select(col("dur").dt.total_seconds(fractional=True))

method

total_milliseconds

def total_milliseconds(*, fractional: bool = False) -> Expr

Total number of milliseconds in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_milliseconds().alias("ms"))

method

total_microseconds

def total_microseconds(*, fractional: bool = False) -> Expr

Total number of microseconds in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_microseconds().alias("us"))

method

total_nanoseconds

def total_nanoseconds(*, fractional: bool = False) -> Expr

Total number of nanoseconds in each duration.

Parameters:

parameter

fractionalbool

If True, include the fractional remainder.

Example:

tf.select(col("dur").dt.total_nanoseconds().alias("ns"))

method

offset_by

def offset_by(by: str | Expr) -> Expr

Shift each datetime by a duration offset.

Parameters:

parameter

bystr | Expr

Offset duration, e.g. 1mo, 1d or -2h; a negative value shifts backwards.

Example:

col("ts").dt.offset_by("1d")  # add one day

method

month_start

def month_start() -> Expr

Return the first day of the month for each date.

Example:

tf.select(col("d").dt.month_start().alias("first_day"))

method

month_end

def month_end() -> Expr

Return the last day of the month for each date.

Example:

tf.select(col("d").dt.month_end().alias("last_day"))

method

base_utc_offset

def base_utc_offset() -> Expr

Return the base UTC offset, excluding daylight saving.

Example:

tf.select(
    col("ts")
    .dt.replace_time_zone("Europe/Madrid")
    .dt.base_utc_offset()
)

method

dst_offset

def dst_offset() -> Expr

Return the additional daylight-saving offset.

Example:

tf.select(
    col("ts")
    .dt.replace_time_zone("Europe/Madrid")
    .dt.dst_offset()
)