polars.datetime_range#

polars.datetime_range(
start: datetime | date | IntoExprColumn,
end: datetime | date | IntoExprColumn,
interval: str | timedelta = '1d',
*,
closed: ClosedInterval = 'both',
time_unit: TimeUnit | None = None,
time_zone: str | None = None,
eager: bool = False,
) Series | Expr[source]#

Generate a datetime range.

Parameters:
start

Lower bound of the datetime range.

end

Upper bound of the datetime range.

interval

Interval of the range periods, specified as a Python timedelta object or using the Polars duration string language (see “Notes” section below).

closed{‘both’, ‘left’, ‘right’, ‘none’}

Define which sides of the range are closed (inclusive).

time_unit{None, ‘ns’, ‘us’, ‘ms’}

Time unit of the resulting Datetime data type.

time_zone

Time zone of the resulting Datetime data type.

eager

Evaluate immediately and return a Series. If set to False (default), return an expression instead.

Returns:
Expr or Series

Column of data type Datetime.

Notes

interval is created according to the following string language:

  • 1ns (1 nanosecond)

  • 1us (1 microsecond)

  • 1ms (1 millisecond)

  • 1s (1 second)

  • 1m (1 minute)

  • 1h (1 hour)

  • 1d (1 calendar day)

  • 1w (1 calendar week)

  • 1mo (1 calendar month)

  • 1q (1 calendar quarter)

  • 1y (1 calendar year)

Or combine them: “3d12h4m25s” # 3 days, 12 hours, 4 minutes, and 25 seconds

By “calendar day”, we mean the corresponding time on the next day (which may not be 24 hours, due to daylight savings). Similarly for “calendar week”, “calendar month”, “calendar quarter”, and “calendar year”.

Examples

Using Polars duration string to specify the interval:

>>> from datetime import datetime
>>> pl.datetime_range(
...     datetime(2022, 1, 1), datetime(2022, 3, 1), "1mo", eager=True
... ).alias("datetime")
shape: (3,)
Series: 'datetime' [datetime[μs]]
[
    2022-01-01 00:00:00
    2022-02-01 00:00:00
    2022-03-01 00:00:00
]

Using timedelta object to specify the interval:

>>> from datetime import date, timedelta
>>> pl.datetime_range(
...     date(1985, 1, 1),
...     date(1985, 1, 10),
...     timedelta(days=1, hours=12),
...     time_unit="ms",
...     eager=True,
... ).alias("datetime")
shape: (7,)
Series: 'datetime' [datetime[ms]]
[
    1985-01-01 00:00:00
    1985-01-02 12:00:00
    1985-01-04 00:00:00
    1985-01-05 12:00:00
    1985-01-07 00:00:00
    1985-01-08 12:00:00
    1985-01-10 00:00:00
]

Specifying a time zone:

>>> pl.datetime_range(
...     datetime(2022, 1, 1),
...     datetime(2022, 3, 1),
...     "1mo",
...     time_zone="America/New_York",
...     eager=True,
... ).alias("datetime")
shape: (3,)
Series: 'datetime' [datetime[μs, America/New_York]]
[
    2022-01-01 00:00:00 EST
    2022-02-01 00:00:00 EST
    2022-03-01 00:00:00 EST
]

Omit eager=True if you want to use datetime_range as an expression:

>>> df = pl.DataFrame(
...     {
...         "date": [
...             date(2024, 1, 1),
...             date(2024, 1, 2),
...             date(2024, 1, 1),
...             date(2024, 1, 3),
...         ],
...         "key": ["one", "one", "two", "two"],
...     }
... )
>>> result = (
...     df.group_by("key")
...     .agg(pl.datetime_range(pl.col("date").min(), pl.col("date").max()))
...     .sort("key")
... )
>>> with pl.Config(fmt_str_lengths=70):
...     print(result)
shape: (2, 2)
┌─────┬─────────────────────────────────────────────────────────────────┐
│ key ┆ date                                                            │
│ --- ┆ ---                                                             │
│ str ┆ list[datetime[μs]]                                              │
╞═════╪═════════════════════════════════════════════════════════════════╡
│ one ┆ [2024-01-01 00:00:00, 2024-01-02 00:00:00]                      │
│ two ┆ [2024-01-01 00:00:00, 2024-01-02 00:00:00, 2024-01-03 00:00:00] │
└─────┴─────────────────────────────────────────────────────────────────┘