polars.Expr.dt.offset_by#

Expr.dt.offset_by(by: str) → Expr[source]#

Offset this date by a relative time offset.

This differs from pl.col("foo") + timedelta in that it can take months and leap years into account. Note that only a single minus sign is allowed in the by string, as the first character.

Parameters:
by

The offset is dictated by the following string language:

  • 1ns (1 nanosecond)

  • 1us (1 microsecond)

  • 1ms (1 millisecond)

  • 1s (1 second)

  • 1m (1 minute)

  • 1h (1 hour)

  • 1d (1 day)

  • 1w (1 week)

  • 1mo (1 calendar month)

  • 1y (1 calendar year)

  • 1i (1 index count)

Returns:
Date/Datetime expression

Examples

>>> from datetime import datetime
>>> df = pl.DataFrame(
...     {
...         "dates": pl.date_range(
...             datetime(2000, 1, 1), datetime(2005, 1, 1), "1y"
...         )
...     }
... )
>>> df.select(
...     [
...         pl.col("dates").dt.offset_by("1y").alias("date_plus_1y"),
...         pl.col("dates").dt.offset_by("-1y2mo").alias("date_min"),
...     ]
... )
shape: (6, 2)
┌─────────────────────┬─────────────────────┐
│ date_plus_1y        ┆ date_min            │
│ ---                 ┆ ---                 │
│ datetime[μs]        ┆ datetime[μs]        │
╞═════════════════════╪═════════════════════╡
│ 2001-01-01 00:00:00 ┆ 1998-11-01 00:00:00 │
│ 2002-01-01 00:00:00 ┆ 1999-11-01 00:00:00 │
│ 2003-01-01 00:00:00 ┆ 2000-11-01 00:00:00 │
│ 2004-01-01 00:00:00 ┆ 2001-11-01 00:00:00 │
│ 2005-01-01 00:00:00 ┆ 2002-11-01 00:00:00 │
│ 2006-01-01 00:00:00 ┆ 2003-11-01 00:00:00 │
└─────────────────────┴─────────────────────┘