We’ve used .join() to combine data based on a key (like a SQL JOIN). But what if you just want to stack two DataFrames on top of each other? In those cases, the Polars concat function provides a simple way to do this.
This is called concatenation, and in Polars, we use pl.concat().
1. Vertical Concatenation (Stacking Rows)
This is the most common use. You have two files (e.g., “January Sales” and “February Sales”) with the same columns, and you want to stack them into one big file.
import polars as pl
df_jan = pl.DataFrame({
"product_id": [1, 2],
"sales": [100, 150]
})
df_feb = pl.DataFrame({
"product_id": [1, 3],
"sales": [200, 50]
})
# Stack them vertically (default behavior)
all_sales = pl.concat([df_jan, df_feb])
print(all_sales)Output:
shape: (4, 2) ┌────────────┬───────┐ │ product_id ┆ sales │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞════════════╪═══════╡ │ 1 ┆ 100 │ │ 2 ┆ 150 │ │ 1 ┆ 200 │ │ 3 ┆ 50 │ └────────────┴───────┘
2. Horizontal Concatenation (Adding Columns)
This is less common, but you can also use concat to add new columns, as long as the row count matches.
df1 = pl.DataFrame({"A": [1, 2]})
df2 = pl.DataFrame({"B": [3, 4], "C": [5, 6]})
# Stack them horizontally
df_wide = pl.concat([df1, df2], how="horizontal")
print(df_wide)Output:
shape: (2, 3) ┌─────┬─────┬─────┐ │ A ┆ B ┆ C │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪══════╪═════╡ │ 1 ┆ 3 ┆ 5 │ │ 2 ┆ 4 ┆ 6 │ └─────┴─────┴─────┘
Key Takeaways
- To stack two DataFrames in Polars, use
pl.concat()for concatenation. - Vertical concatenation stacks rows from multiple files with the same columns into one DataFrame.
- Horizontal concatenation adds new columns to a DataFrame, provided that the row counts match.
