Build a taller table
Appending partitioned or batch DataFrames with matching columns.
Polars · Function
pl.concat
Combines multiple DataFrames, LazyFrames, or Series into one object. Choose row-wise, schema-union, horizontal, or key-alignment behavior with how.
How it works
Pass an iterable of DataFrames, LazyFrames, or Series and choose a concatenation strategy with how. The default vertical strategy appends rows; other strategies can merge schemas, place columns side by side, or align frames. Rechunking is disabled by default, while parallel affects only lazy computations.
Syntax
polars.concat(items: Iterable[PolarsType], *, how: ConcatMethod = 'vertical', rechunk: bool = False, parallel: bool = True, strict: bool | None = None) → PolarsTypeParameters
| Name | Type | Description |
|---|---|---|
items | Iterable[PolarsType] | DataFrames, LazyFrames, or Series to concatenate. |
how | ConcatMethod = 'vertical' | Concatenation strategy: vertical, vertical_relaxed, diagonal, diagonal_relaxed, horizontal, horizontal_extend, align, align_full, align_inner, align_left, or align_right. |
rechunk | bool = False | Whether to make the result data contiguous in memory. |
parallel | bool = True | Whether concatenated lazy computations may execute in parallel; relevant only to LazyFrames. |
strict | bool | None = None | Whether strict schema handling is enabled when applicable. |
Returns
PolarsType: a concatenated DataFrame, LazyFrame, or Series.
Key points
- Use pl.concat to combine multiple Polars tabular objects into one result.
- The vertical method appends rows in sequence.
- The relaxed vertical method promotes incompatible corresponding dtypes to common supertypes.
- Diagonal concatenation supports different schemas by unioning columns and inserting nulls where a frame lacks a column.
- Horizontal concatenation places columns side by side.
- Alignment strategies infer common key columns and arrange rows accordingly.
- Set rechunk=True when the output should occupy contiguous memory.
Common mistakes
- With how="horizontal", inputs must have equal heights; otherwise Polars raises a ShapeError.
- Series cannot use the horizontal, diagonal, or alignment strategies.
- parallel matters only for LazyFrames, not eager DataFrames or Series.
Example: Vertical concatenation
import polars as pl
a = pl.DataFrame({"id": [1, 2], "value": ["a", "b"]})
b = pl.DataFrame({"id": [3], "value": ["c"]})
result = pl.concat([a, b])
print(result)Combines the rows of two DataFrames with matching schemas.
When to use it
Union heterogeneous schemas
Merging frames whose columns differ across sources.
Align related tables
Combining compatible frames by inferred common keys.
Interview questions
QWhat does the default concatenation strategy do?
The default is how="vertical", which applies multiple vstack operations. It is appropriate when frames have compatible columns and should become one taller frame.
Follow-up: How would you combine frames with different schemas? Use how="diagonal" to take the schema union and fill absent values with null.
QWhen would you choose vertical_relaxed?
how="vertical_relaxed" performs vertical concatenation while coercing unequal column dtypes to compatible supertypes. This is useful when corresponding columns differ in type but can be promoted safely.
Follow-up: What is the analogous strategy for differing schemas? Use how="diagonal_relaxed", which combines schema union behavior with dtype coercion.
QWhich inputs does polars.concat accept, and what does parallel mean?
The function accepts DataFrames, LazyFrames, or Series and returns a Polars object matching the input family. The parallel flag controls whether concatenated lazy computations may execute concurrently.
Follow-up: What does rechunk control? It requests contiguous memory for the result, but its stable default is False.
Related
polars.concat_strpolars.concat_listpolars.concat_arrpolars.align_framesDataFrame.vstackDataFrame.hstack