Derive columns
Create calculated fields such as totals, ratios, flags, or powers from existing columns.
Polars · Function
with_columns
Adds expression-derived columns to a DataFrame while retaining existing columns. Columns with names already present are replaced, and the returned DataFrame reuses existing data rather than copying it.
How it works
Call with_columns with expressions as positional arguments or keyword arguments. Polars evaluates those expressions to produce columns, keeps the existing columns, and returns a new DataFrame; assigning an existing name replaces that column without copying the existing data.
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
A new DataFrame with the columns added.
Key points
- Use the method to derive and append columns without discarding the DataFrame's existing columns.
- Expressions such as arithmetic, casts, and aliases are valid positional column specifications.
- Keyword arguments provide a concise way to add named expressions.
- A keyword argument determines the resulting column name, regardless of the expression's original name.
- The return value is a separate DataFrame result containing the additions.
- Existing data is not duplicated merely because the method returns a new DataFrame.
Common mistakes
- Using an output name that already exists overwrites that column in the returned DataFrame.
- A bare string refers to a column rather than becoming a literal string value; use an explicit literal expression when needed.
Example: Add derived columns
import polars as pl
df = pl.DataFrame({"a": [1, 2, 3], "b": [10, 20, 30]})
result = df.with_columns(
(pl.col("a") * 2).alias("a_twice"),
total=pl.col("a") + pl.col("b"),
)
print(result)Adds an expression-based column and a keyword-named column while retaining the original columns.
When to use it
Transform existing columns
Change a column's dtype or transform its values while keeping the rest of the DataFrame.
Batch column construction
Add several named expressions in one DataFrame operation.
Interview questions
QWhat does DataFrame.with_columns do?
with_columns returns a new DataFrame containing the original columns plus columns computed from the supplied expressions. Positional expressions can name their outputs with alias, while keyword expressions use the keyword as the output name.
Follow-up: How does it differ from select? with_columns preserves the existing columns, whereas select returns only the expressions it selects.
QHow can columns be named when using with_columns?
The method accepts positional exprs and keyword named_exprs. Positional inputs accept expression input; keyword names determine the names of the added columns.
Follow-up: How can one expression be given a custom name? Call .alias("desired_name") on the expression before passing it.
QDoes with_columns copy the existing data?
It produces a new DataFrame, but creating that DataFrame does not create a new copy of the existing data. Expressions calculate the added or replaced columns in the returned result.
Follow-up: When might with_columns_seq be preferable? It runs expressions sequentially and is intended for cases where the work per expression is cheap.
Related
DataFrame.with_columns_seqDataFrame.selectpolars.col