polars.date_diff#
- polars.date_diff(
- start: date | datetime | time | IntoExprColumn,
- end: date | datetime | time | IntoExprColumn,
- unit: DateDiffUnit,
Count the
unitboundaries crossed fromstarttoend.This counts how often the calendar or clock moves into a new
uniton the way fromstarttoend. For example, 2024-01-31 to 2024-02-01 is 1 month, while 2024-01-01 to 2024-01-31 is 0 months. The count is negative ifendis beforestart.Weeks start on Monday. For time zone-aware datetimes, the boundaries are those of the wall-clock time in their time zone.
- Parameters:
- start
Start values of type Date, Datetime or Time. Strings are parsed as column names.
- end
End values. A Date combined with a Datetime is taken as midnight, which is midnight UTC for a time zone-aware Datetime, as in other operations.
- unit
The unit to count: one of ‘year’, ‘quarter’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘millisecond’, ‘microsecond’ or ‘nanosecond’. Time values only support units shorter than a day.
- Returns:
- Expr
Expression of data type
Int64.
Examples
>>> from datetime import date >>> df = pl.DataFrame( ... { ... "start": [date(2024, 1, 31), date(2024, 12, 31), date(2024, 3, 10)], ... "end": [date(2024, 2, 1), date(2025, 1, 1), date(2024, 3, 4)], ... } ... ) >>> df.with_columns( ... days=pl.date_diff("start", "end", "day"), ... months=pl.date_diff("start", "end", "month"), ... years=pl.date_diff("start", "end", "year"), ... ) shape: (3, 5) ┌────────────┬────────────┬──────┬────────┬───────┐ │ start ┆ end ┆ days ┆ months ┆ years │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ date ┆ date ┆ i64 ┆ i64 ┆ i64 │ ╞════════════╪════════════╪══════╪════════╪═══════╡ │ 2024-01-31 ┆ 2024-02-01 ┆ 1 ┆ 1 ┆ 0 │ │ 2024-12-31 ┆ 2025-01-01 ┆ 1 ┆ 1 ┆ 1 │ │ 2024-03-10 ┆ 2024-03-04 ┆ -6 ┆ 0 ┆ 0 │ └────────────┴────────────┴──────┴────────┴───────┘
Only boundaries count, so 10:59 to 11:01 is one hour.
>>> from datetime import datetime >>> df = pl.DataFrame( ... { ... "start": [datetime(2024, 1, 1, 10, 59), datetime(2024, 1, 1, 10, 0)], ... "end": [datetime(2024, 1, 1, 11, 1), datetime(2024, 1, 1, 10, 59)], ... } ... ) >>> df.with_columns( ... hours=pl.date_diff("start", "end", "hour"), ... minutes=pl.date_diff("start", "end", "minute"), ... ) shape: (2, 4) ┌─────────────────────┬─────────────────────┬───────┬─────────┐ │ start ┆ end ┆ hours ┆ minutes │ │ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ datetime[μs] ┆ i64 ┆ i64 │ ╞═════════════════════╪═════════════════════╪═══════╪═════════╡ │ 2024-01-01 10:59:00 ┆ 2024-01-01 11:01:00 ┆ 1 ┆ 2 │ │ 2024-01-01 10:00:00 ┆ 2024-01-01 10:59:00 ┆ 0 ┆ 59 │ └─────────────────────┴─────────────────────┴───────┴─────────┘