Derived columns
Create calculated fields from one or more existing columns.
Polars · Module
df.with_columns
Adds expression-derived or literal columns to a DataFrame while retaining existing columns. Existing names are replaced, and keyword expressions use their keywords as output names.
How it works
Call with_columns with expressions as positional arguments or with keyword expressions. Polars evaluates those expressions to produce a new DataFrame containing the original columns plus the requested results; a result with an existing name replaces that column, while keyword names determine output names.
Syntax
DataFrame.with_columns(*exprs: IntoExpr | Iterable[IntoExpr], **named_exprs: IntoExpr) → DataFrameParameters
| Name | Type | Description |
|---|---|---|
*exprs | IntoExpr | Iterable[IntoExpr] | Column(s) to add, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. |
**named_exprs | IntoExpr | Additional columns to add, specified as keyword arguments. The columns will be renamed to the keyword used. |
Returns
DataFrame — a new DataFrame with the columns added.
Key points
- Use the method to append computed or literal columns to a DataFrame.
- The positional input is designed for Polars expressions, such as column arithmetic, casts, and aliases.
- Keyword expressions offer a concise naming form for derived columns.
- A keyword expression uses its keyword as the resulting column name.
- The operation returns a separate DataFrame value rather than modifying the receiver in place.
- Existing data is not copied when the new DataFrame is constructed.
Common mistakes
- An expression that produces an existing column name overwrites that column in the returned DataFrame.
- Passing a plain string refers to a column rather than creating a string-valued literal; use an expression for explicit literal behavior.
Example: Add derived columns
import polars as pl
df = pl.DataFrame({"a": [1, 2], "b": [10, 20]})
result = df.with_columns(
(pl.col("a") * 2).alias("a_doubled"),
total=pl.col("a") + pl.col("b"),
)
print(result)Adds two derived columns while retaining the original columns.
When to use it
Column transformations
Convert a column's data type while preserving the rest of the frame.
Named expression outputs
Add several named results compactly with keyword expressions.
Interview questions
QWhat does with_columns return?
with_columns returns a new DataFrame containing the added columns. Existing columns remain available, and an added column with an existing name replaces that column.
Follow-up: How can output names be assigned without calling alias? Use keyword expressions, because the keyword becomes the column name.
QHow can multiple columns be added?
Positional arguments accept expression inputs, and multiple expressions can be supplied either individually or through an iterable. Keyword expressions provide an additional way to add and name columns.
Follow-up: What happens to a non-expression positional value? It is parsed as a literal, whereas a string is interpreted as a column name.
QDoes with_columns copy existing data?
The method creates a new DataFrame without copying the existing data. This preserves the original frame's data storage while presenting the requested columns in the result.
Follow-up: Which related method changes expression execution order? with_columns_seq runs expressions sequentially instead of in parallel.
Related
DataFrame.with_columns_seqDataFrame.selectpolars.col