Implementation:Pola rs Polars Expr Cast and Transform
| Knowledge Sources | |
|---|---|
| Domains | Data_Engineering, Type_Systems, Data_Cleaning |
| Last Updated | 2026-02-09 10:00 GMT |
Overview
Concrete APIs for casting column data types, parsing temporal strings, renaming columns, and creating computed columns using Polars expressions.
Description
The Expr Cast and Transform APIs provide the building blocks for reshaping data after ingestion. DataFrame.with_columns applies one or more expressions to add or replace columns. Expr.cast converts values to a target DataType. Expr.str.to_date parses date strings using format specifiers. DataFrame.rename remaps column names. Expr.alias assigns a name to computed expression results.
Usage
Import polars and chain transformation operations after reading data. Use with_columns to apply multiple transformations in a single call for efficiency. These APIs work identically on both DataFrame and LazyFrame objects.
Code Reference
Source Location
- Repository: polars
- File: docs/source/src/python/user-guide/getting-started.py
- Lines: 28-56
Signature
# Add or replace columns using expressions
DataFrame.with_columns(*exprs: Expr | list[Expr]) -> DataFrame
LazyFrame.with_columns(*exprs: Expr | list[Expr]) -> LazyFrame
# Cast a column to a different data type
Expr.cast(dtype: DataType, strict: bool = True) -> Expr
# Rename columns using a mapping dictionary
DataFrame.rename(mapping: dict[str, str]) -> DataFrame
# Parse string column to Date type
Expr.str.to_date(format: str = None) -> Expr
# Parse string column to Datetime type
Expr.str.to_datetime(format: str = None) -> Expr
# Assign a name to an expression result
Expr.alias(name: str) -> Expr
Import
import polars as pl
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| exprs | Expr or list[Expr] | Yes (with_columns) | One or more Polars expressions defining column transformations |
| dtype | polars.DataType | Yes (cast) | Target data type (e.g., pl.Float64, pl.Int32, pl.Utf8, pl.Date) |
| strict | bool | No | If True (default), raise on cast failure; if False, return null for failed casts |
| format | str | No | Date/datetime format string (e.g., "%Y-%m-%d") for string-to-temporal parsing |
| mapping | dict[str, str] | Yes (rename) | Dictionary mapping old column names to new column names |
| name | str | Yes (alias) | Name to assign to the expression result column |
Outputs
| Name | Type | Description |
|---|---|---|
| DataFrame | polars.DataFrame | Transformed DataFrame with new/modified columns (eager mode) |
| LazyFrame | polars.LazyFrame | Transformed LazyFrame with new/modified columns (lazy mode) |
| Expr | polars.Expr | Intermediate expression (from cast, alias, str.to_date) to be used within with_columns |
Usage Examples
import polars as pl
df = pl.read_csv("data.csv")
# Cast a column to Float64
df = df.with_columns(pl.col("price").cast(pl.Float64))
# Parse date strings to Date type
df = df.with_columns(pl.col("date_str").str.to_date("%Y-%m-%d"))
# Rename columns
df = df.rename({"old_name": "new_name"})
# Create computed columns
df = df.with_columns(
(pl.col("weight") / (pl.col("height") ** 2)).alias("bmi")
)
# Multiple transformations in a single with_columns call
df = df.with_columns(
pl.col("amount").cast(pl.Float64),
pl.col("created_at").str.to_datetime("%Y-%m-%dT%H:%M:%S"),
(pl.col("quantity") * pl.col("unit_price")).alias("total"),
)
# Non-strict cast (returns null instead of error on failure)
df = df.with_columns(
pl.col("maybe_numeric").cast(pl.Int64, strict=False)
)