Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Expressions

Date and Time Expressions

Work with dates in Polars: Date and Datetime types, parsing, the dt namespace, truncation, arithmetic with durations, time zones, date ranges and rolling windows.

Dates and times are everywhere in data: orders, logs, sensor readings. Polars has first-class temporal types and a dt namespace for pulling parts out of them, shifting them and rounding them. Because dates are stored as integers internally, these operations are very fast.

The temporal types

  • pl.Date: a calendar day, no time.
  • pl.Datetime: day plus time, with a precision ("ms", "us", "ns") and an optional time zone.
  • pl.Time: a time of day.
  • pl.Duration: a length of time, the result of subtracting two datetimes.

Parsing text into dates

Python Parsing dates and datetimes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

ISO strings (YYYY-MM-DD) parse without a format. Other layouts use strftime-style codes: %Y year, %m month, %d day, %H hour, %M minute, %S second. Add strict=False to turn unparseable values into null. Building dates from Python objects is simplest: datetime.date(2025, 3, 1) creates a Date column.

Pulling out parts with dt

Python The dt namespace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

dt.to_string(format) (also dt.strftime) formats a date back to text. Remember that weekday() numbers Monday as 1, which differs from Python's datetime.weekday() (Monday = 0).

Truncating and rounding

dt.truncate rounds a timestamp down to the start of a period: a very common step before grouping by day, week or month.

Python truncate and group by month

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The interval strings are compact: "1d", "1w", "1mo", "1q", "1y", "15m", "1h". dt.round goes to the nearest period instead of down. For calendar-based grouping over time Polars also has group_by_dynamic, covered in the windows chapter.

Arithmetic with durations

Subtracting two datetimes gives a Duration; adding a duration shifts a datetime. dt.offset_by understands calendar units such as months, which have uneven lengths.

Python Durations and offsets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

pl.duration(days=..., hours=...) builds durations from columns or numbers inside expressions. Methods like total_hours() and total_seconds() turn a Duration into a plain number.

Date ranges

pl.date_range and pl.datetime_range create regular sequences, handy for filling gaps or building calendars.

Python Date ranges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

On a normal install, pl.date_range(start, end, "1d") is the usual way to list days. The in-browser build is 32-bit and rejects intervals longer than about 70 minutes expressed in microseconds, so the example above builds the days from an integer range instead. Monthly and hourly ranges work in both.

Time zones

A naive datetime has no zone. Attach one with dt.replace_time_zone (says "these clock readings are in this zone") and convert between zones with dt.convert_time_zone (same instant, different clock).

Python Time zones

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Named zones such as Asia/Tokyo use the IANA time-zone database. Polars bundles what it needs, so they work in the browser runner too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does subtracting two Datetime columns produce?

    The difference between two datetimes is a Duration. Use dt.total_days() or similar to get a number.
  2. 2. Which expression gives the first day of the month for each date in column d?

    truncate rounds down to the start of the period; '1mo' is one month.
  3. 3. In Polars, which number does dt.weekday() give to Monday?

    dt.weekday() runs from 1 (Monday) to 7 (Sunday), following ISO 8601.
  4. 4. What is the difference between replace_time_zone and convert_time_zone?

    replace_time_zone attaches a zone to a naive time (or relabels). convert_time_zone shows the same instant in another zone.

Summary

  • Use Date, Datetime, Time and Duration; parse text with str.to_date/to_datetime and format strings.
  • The dt namespace extracts parts (year, month, weekday...), formats, truncates and rounds.
  • Datetime subtraction gives a Duration; offset_by handles calendar months.
  • date_range/datetime_range build sequences; use replace_time_zone and convert_time_zone for zones.

Next: When, Then, Otherwise