polars.date_range#

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

Create a range of type Datetime (or Date).

Parameters:
start

Lower bound of the date range, given as a date, datetime, Expr, or column name.

end

Upper bound of the date range, given as a date, datetime, Expr, or column name.

interval

Interval of the range periods; can be a python timedelta object like timedelta(days=10) or a polars duration string, such as 3d12h4m25s (representing 3 days, 12 hours, 4 minutes, and 25 seconds).

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

Define whether the temporal window interval is closed or not.

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

Set the time unit.

time_zone:

Optional timezone

eager

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

name

Name of the output column.

Deprecated since version 0.18.0: This argument is deprecated. Use the alias method instead.

Returns:
A Series of type Datetime or Date.

Notes

If both start and end are passed as date types (not datetime), and the interval granularity is no finer than 1d, the returned range is also of type date. All other permutations return a datetime Series.

Examples

Using polars duration string to specify the interval:

>>> from datetime import date
>>> pl.date_range(date(2022, 1, 1), date(2022, 3, 1), "1mo", eager=True)
shape: (3,)
Series: 'date' [date]
[
    2022-01-01
    2022-02-01
    2022-03-01
]

Using timedelta object to specify the interval:

>>> from datetime import datetime, timedelta
>>> pl.date_range(
...     datetime(1985, 1, 1),
...     datetime(1985, 1, 10),
...     timedelta(days=1, hours=12),
...     time_unit="ms",
...     eager=True,
... )
shape: (7,)
Series: 'date' [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
]

Specify a time zone

>>> pl.date_range(
...     datetime(2022, 1, 1),
...     datetime(2022, 3, 1),
...     "1mo",
...     time_zone="America/New_York",
...     eager=True,
... )
shape: (3,)
Series: 'date' [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
]

Combine with month_end to get the last day of the month:

>>> (
...     pl.date_range(
...         datetime(2022, 1, 1), datetime(2022, 3, 1), "1mo", eager=True
...     ).dt.month_end()
... )
shape: (3,)
Series: 'date' [datetime[μs]]
[
    2022-01-31 00:00:00
    2022-02-28 00:00:00
    2022-03-31 00:00:00
]