polars.duration#

polars.duration(*, days: Optional[Union[Expr, str, int]] = None, seconds: Optional[Union[Expr, str, int]] = None, nanoseconds: Optional[Union[Expr, str, int]] = None, microseconds: Optional[Union[Expr, str, int]] = None, milliseconds: Optional[Union[Expr, str, int]] = None, minutes: Optional[Union[Expr, str, int]] = None, hours: Optional[Union[Expr, str, int]] = None, weeks: Optional[Union[Expr, str, int]] = None) Expr[source]#

Create polars Duration from distinct time components.

Returns:
Expr of type pl.Duration

Examples

>>> from datetime import datetime
>>> df = pl.DataFrame(
...     {
...         "datetime": [datetime(2022, 1, 1), datetime(2022, 1, 2)],
...         "add": [1, 2],
...     }
... )
>>> df.select(
...     [
...         (pl.col("datetime") + pl.duration(weeks="add")).alias("add_weeks"),
...         (pl.col("datetime") + pl.duration(days="add")).alias("add_days"),
...         (pl.col("datetime") + pl.duration(seconds="add")).alias("add_seconds"),
...         (pl.col("datetime") + pl.duration(milliseconds="add")).alias(
...             "add_milliseconds"
...         ),
...         (pl.col("datetime") + pl.duration(hours="add")).alias("add_hours"),
...     ]
... )  
shape: (2, 5)
┌────────────┬────────────┬─────────────────────┬──────────────┬─────────────────────┐
│ add_weeks  ┆ add_days   ┆ add_seconds         ┆ add_millisec ┆ add_hours           │
│ ---        ┆ ---        ┆ ---                 ┆ onds         ┆ ---                 │
│ datetime[m ┆ datetime[m ┆ datetime[ms]        ┆ ---          ┆ datetime[ms]        │
│ s]         ┆ s]         ┆                     ┆ datetime[ms] ┆                     │
╞════════════╪════════════╪═════════════════════╪══════════════╪═════════════════════╡
│ 2022-01-08 ┆ 2022-01-02 ┆ 2022-01-01 00:00:01 ┆ 2022-01-01   ┆ 2022-01-01 01:00:00 │
│ 00:00:00   ┆ 00:00:00   ┆                     ┆ 00:00:00.001 ┆                     │
├╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 2022-01-16 ┆ 2022-01-04 ┆ 2022-01-02 00:00:02 ┆ 2022-01-02   ┆ 2022-01-02 02:00:00 │
│ 00:00:00   ┆ 00:00:00   ┆                     ┆ 00:00:00.002 ┆                     │
└────────────┴────────────┴─────────────────────┴──────────────┴─────────────────────┘