Polars Adding Days to a Date

In Polars, adding days to a date refers to updating a Date or Datetime column (or value) by increasing or decreasing it by a specific number of days. This is accomplished using time durations, which represent intervals like days, hours, or minutes. It's particularly useful for tasks such as scheduling, forecasting, or adjusting timelines. The operation is typically performed using pl.col() combined with pl.duration() for clear and efficient time-based data manipulation. In this article, I will explain how to add days to a date in polars.

Key Points –

Polars uses the pl.duration() function to represent a time duration (e.g., days, hours).
You can add days to a date or datetime column using the + operator with pl.duration().
To subtract days, pass a negative value to pl.duration() or use the - operator.
pl.duration() supports multiple time units: days, hours, minutes, seconds, etc.
Fractional days must be expressed using hours, minutes, or seconds since pl.duration only accepts integers.
You can use a variable inside pl.duration() to make the addition dynamic.
It's possible to add days based on values from another column by referencing it in pl.duration().
Calculated expressions (e.g., column * constant) can be used to compute how many days to add.

Usage of Polars Adding Days to a Date

To add days to a date column in Polars, you can use the pl.duration() function to create a duration and then add that to the date column.

Now, let’s create a Polars DataFrame.


import polars as pl
from datetime import date

# Create a DataFrame with a date column
df = pl.DataFrame({
    "start_date": [date(2024, 1, 5), date(2024, 5, 10), date(2024, 12, 31)]
})
print("Original DataFrame:\n", df)

Yields below output.

To add a fixed number of days (e.g., 10 days) to a date column in a Polars DataFrame, use the pl.duration() function to create a day-based duration and add it directly to the date column.


# Add 10 days to each date in the "start_date" column
df2 = df.with_columns(
    (pl.col("start_date") + pl.duration(days=10)).alias("new_date")
)
print("DataFrame with 10 days added:\n", df2)

Here,

The start_date column contains the original dates.
pl.duration(days=10) creates a duration of 10 days.
The + operator adds 10 days to each value in the start_date column.
The with_columns() function adds the new new_date column to the DataFrame.

Add Negative Days (Subtract Days)

You can subtract a fixed number of days (e.g., 5 days) from a date column in Polars by passing a negative value to pl.duration(days=…).


# Subtract 5 days from each date
df = df.with_columns(
    (pl.col("start_date") + pl.duration(days=-5)).alias("minus_5_days")
)
print("DataFrame with 5 days subtracted:\n", df)

# Output:
# DataFrame with 5 days subtracted:
# shape: (3, 2)
┌────────────┬──────────────┐
│ start_date ┆ minus_5_days │
│ ---        ┆ ---          │
│ date       ┆ date         │
╞════════════╪══════════════╡
│ 2024-01-05 ┆ 2023-12-31   │
│ 2024-05-10 ┆ 2024-05-05   │
│ 2024-12-31 ┆ 2024-12-26   │
└────────────┴──────────────┘

Here,

Using pl.duration(days=-5) creates a duration representing minus 5 days.
Adding this to the date effectively subtracts 5 days.

Add Days Based on a Variable Value

You can add days to a date column in Polars based on a variable by defining the value (e.g., days_to_add = 15) and using it with pl.duration(days=days_to_add).


# Define variable
days_to_add = 15

# Add variable number of days
df = df.with_columns(
    (pl.col("start_date") + pl.duration(days=days_to_add)).alias("plus_variable_days")
)
print("Days added using variable:\n", df)

# Output:
# Days added using variable:
# shape: (3, 2)
┌────────────┬────────────────────┐
│ start_date ┆ plus_variable_days │
│ ---        ┆ ---                │
│ date       ┆ date               │
╞════════════╪════════════════════╡
│ 2024-01-05 ┆ 2024-01-20         │
│ 2024-05-10 ┆ 2024-05-25         │
│ 2024-12-31 ┆ 2025-01-15         │
└────────────┴────────────────────┘

Here,

days_to_add = 15: You set the number of days to add using a variable.
pl.duration(days=days_to_add): Uses that variable to create the duration.
The addition works vectorized for all values in start_date.

Add Fractional Days (Representing Hours and Minutes)

Polars allows you to add fractional days by converting them into hours, minutes, or seconds using the pl.duration() function. While you can't use decimal days directly, you can achieve the same effect by specifying the corresponding time units.


# Add 1.5 days as 36 hours
df2 = df.with_columns(
    (pl.col("start_date") + pl.duration(hours=36)).alias("plus_1_5_days")
)
print("DataFrame with 1.5 days added:\n", df2)

# Output:
# DataFrame with 1.5 days added:
# shape: (3, 2)
┌────────────┬───────────────┐
│ start_date ┆ plus_1_5_days │
│ ---        ┆ ---           │
│ date       ┆ date          │
╞════════════╪═══════════════╡
│ 2024-01-05 ┆ 2024-01-06    │
│ 2024-05-10 ┆ 2024-05-11    │
│ 2024-12-31 ┆ 2025-01-01    │
└────────────┴───────────────┘

Here,

The resulting column becomes datetime (with time), not just a date.
You can add minutes, seconds, or even microseconds similarly using pl.duration().

Add Days Using a Column Value (Dynamic Addition)

To dynamically add days based on a column value (i.e., using the value from another column to determine the number of days to add), you can directly reference that column and pass it to the pl.duration() function.


import polars as pl
from datetime import date

# Create a DataFrame with start_date and days_to_add columns
df = pl.DataFrame({
    "start_date": [date(2025, 1, 1), date(2025, 5, 10), date(2025, 12, 31)],
    "days_to_add": [5, 10, 15]
})

# Dynamically add days from the "days_to_add" column
df2 = df.with_columns(
    (pl.col("start_date") + pl.duration(days=pl.col("days_to_add"))).alias("new_date")
)
print("DataFrame with dynamic days added:\n", df2)

# Output:
# DataFrame with dynamic days added:
# shape: (3, 3)
┌────────────┬─────────────┬────────────┐
│ start_date ┆ days_to_add ┆ new_date   │
│ ---        ┆ ---         ┆ ---        │
│ date       ┆ i64         ┆ date       │
╞════════════╪═════════════╪════════════╡
│ 2025-01-01 ┆ 5           ┆ 2025-01-06 │
│ 2025-05-10 ┆ 10          ┆ 2025-05-20 │
│ 2025-12-31 ┆ 15          ┆ 2026-01-15 │
└────────────┴─────────────┴────────────┘

Here,

pl.col("start_date"): Selects the start_date column.
pl.col("days_to_add"): Selects the days_to_add column, which contains the number of days to add dynamically for each row.
pl.duration(days=pl.col("days_to_add")): Uses the value from days_to_add to create a duration.
The result is a new column, new_date, with the dynamically adjusted dates.

Add Days from a Calculated Expression (e.g., Multiplying a Number)

You can add days in Polars using a calculated expression, such as multiplying a numeric column by a constant. This is useful when the number of days to add is computed rather than fixed.


import polars as pl
from datetime import date

# Create the DataFrame with a numeric column
df = pl.DataFrame({
    "start_date": [date(2025, 2, 5), date(2025, 6, 10), date(2025, 10, 21)],
    "base_value": [3, 5, 7]  # Each row will add base_value * 2 days
})

# Add days from a calculated expression
df = df.with_columns(
    (pl.col("start_date") + pl.duration(days=pl.col("base_value") * 2)).alias("new_date")
)
print("Days added using calculated expression:\n", df)

# Output:
# Days added using calculated expression:
# shape: (3, 3)
┌────────────┬────────────┬────────────┐
│ start_date ┆ base_value ┆ new_date   │
│ ---        ┆ ---        ┆ ---        │
│ date       ┆ i64        ┆ date       │
╞════════════╪════════════╪════════════╡
│ 2025-02-05 ┆ 3          ┆ 2025-02-11 │
│ 2025-06-10 ┆ 5          ┆ 2025-06-20 │
│ 2025-10-21 ┆ 7          ┆ 2025-11-04 │
└────────────┴────────────┴────────────┘

Here,

pl.col("base_value") * 2: The number of days is calculated by multiplying the base_value column by 2.
pl.duration(days=...): Wraps the result as a duration.
This approach is dynamic and flexible for any computation-based adjustment.

Conclusion

In conclusion, adding days to a date column in Polars is straightforward and highly flexible. Whether you're working with a fixed value, a variable, another column, or a dynamically calculated expression, pl.duration() offers a clean and efficient solution. It provides precise control over date operations, making time-based data manipulation in large datasets both fast and intuitive.

Happy Learning!!

Reference

https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.date_range.html

Polars Adding Days to a Date

Usage of Polars Adding Days to a Date

Add Negative Days (Subtract Days)

Add Days Based on a Variable Value

Add Fractional Days (Representing Hours and Minutes)

Add Days Using a Column Value (Dynamic Addition)

Add Days from a Calculated Expression (e.g., Multiplying a Number)

Conclusion

Related Articles

Reference