Polars

High-performance DataFrame library built on Apache Arrow. Supports Python and Rust with expression-based API, lazy evaluation, and automatic parallelization.

Quick Start

Python

bash
1uv pip install polars
2# GPU support: uv pip install polars[gpu]

python
1import polars as pl
2
3# Eager: immediate execution
4df = pl.DataFrame({"symbol": ["AAPL", "GOOG"], "price": [150.0, 140.0]})
5df.filter(pl.col("price") > 145).select("symbol", "price")
6
7# Lazy: optimized execution (preferred for large data)
8lf = pl.scan_parquet("trades.parquet")
9result = lf.filter(pl.col("volume") > 1000).group_by("symbol").agg(
10    pl.col("price").mean().alias("avg_price")
11).collect()

Rust

toml
1# Cargo.toml - select features you need
2[dependencies]
3polars = { version = "0.46", features = ["lazy", "parquet", "temporal"] }

rust
1use polars::prelude::*;
2
3fn main() -> PolarsResult<()> {
4    // Eager
5    let df = df![
6        "symbol" => ["AAPL", "GOOG"],
7        "price" => [150.0, 140.0]
8    ]?;
9
10    // Lazy (preferred)
11    let lf = LazyFrame::scan_parquet("trades.parquet", Default::default())?;
12    let result = lf
13        .filter(col("volume").gt(lit(1000)))
14        .group_by([col("symbol")])
15        .agg([col("price").mean().alias("avg_price")])
16        .collect()?;
17    Ok(())
18}

Core Pattern: Expressions

Everything in Polars is an expression. Expressions are composable, lazy, and parallelized.

python
1# Expression building blocks
2pl.col("price")                      # column reference
3pl.col("price") * pl.col("volume")   # arithmetic
4pl.col("price").mean().over("symbol") # window function
5pl.when(cond).then(a).otherwise(b)   # conditional

Expressions execute in contexts: select(), with_columns(), filter(), group_by().agg()

When to Use Lazy

Lazy benefits: predicate pushdown, projection pushdown, parallel execution, streaming.

Style: Use .alias() for Column Naming

Always use .alias("name") instead of name=expr kwargs:

python
1# GOOD: Explicit .alias() - works everywhere, composable
2df.with_columns(
3    (pl.col("price") * pl.col("volume")).alias("value"),
4    pl.col("price").mean().over("symbol").alias("avg_price")
5)
6
7# AVOID: Kwarg style - less flexible, doesn't chain
8df.with_columns(
9    value=pl.col("price") * pl.col("volume"),  # avoid
10    avg_price=pl.col("price").mean().over("symbol")  # avoid
11)

.alias() is explicit, chains with other methods, and works consistently in all contexts.

Anti-Patterns - AVOID

python
1# BAD: Python functions kill parallelization
2df.with_columns(pl.col("x").map_elements(lambda x: x * 2))  # SLOW
3
4# GOOD: Native expressions are parallel
5df.with_columns((pl.col("x") * 2).alias("x"))  # FAST
6
7# BAD: Row iteration
8for row in df.iter_rows():  # SLOW
9    process(row)
10
11# GOOD: Columnar operations
12df.with_columns(process_expr)  # FAST
13
14# BAD: Late projection
15lf.filter(...).collect().select("a", "b")  # reads all columns
16
17# GOOD: Early projection
18lf.select("a", "b").filter(...).collect()  # reads only needed columns

Performance Checklist

• Using scan_* (lazy) for large files?
• Projecting columns early in pipeline?
• Using native expressions (no map_elements)?
• Categorical dtype for low-cardinality strings?
• Appropriate integer sizes (i32 vs i64)?
• Streaming for out-of-memory data? (collect(engine="streaming"))

Reference Navigator

Python References

Rust References

Shared References

Migration Guides

Time Series / Financial Data Quick Patterns

python
1# OHLCV resampling
2df.group_by_dynamic("timestamp", every="1m").agg(
3    pl.col("price").first().alias("open"),
4    pl.col("price").max().alias("high"),
5    pl.col("price").min().alias("low"),
6    pl.col("price").last().alias("close"),
7    pl.col("volume").sum()
8)
9
10# Rolling statistics
11df.with_columns(
12    pl.col("price").rolling_mean(window_size=20).alias("sma_20"),
13    pl.col("price").rolling_std(window_size=20).alias("volatility")
14)
15
16# As-of join for market data alignment
17trades.join_asof(quotes, on="timestamp", by="symbol", strategy="backward")

Load python/best_practices.md for comprehensive time series patterns.

Runnable Examples

Development Tips

Use LSP for navigating Polars code:

• Python: Pyright/Pylance provides excellent type inference for Polars expressions
• Rust: rust-analyzer understands Polars types and expression chains

LSP operations like goToDefinition and hover help explore Polars API without leaving the editor.