polars

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polars Fast DataFrame Library

Polars 快速DataFrame库

Lightning-fast DataFrame library with lazy evaluation and parallel execution.

具备延迟计算和并行执行能力的超高速DataFrame库。

When to Use

适用场景

Pandas is too slow for your dataset
Working with 1-100GB datasets that fit in RAM
Need lazy evaluation for query optimization
Building ETL pipelines
Want parallel execution without extra config

Pandas处理你的数据集速度过慢
处理1-100GB且可放入内存的数据集
需要通过延迟计算优化查询
构建ETL管道
无需额外配置即可实现并行执行

Lazy vs Eager Evaluation

延迟计算 vs 即时计算

Mode	Function	Executes	Use Case
Eager	`read_csv()`	Immediately	Small data, exploration
Lazy	`scan_csv()`	On `.collect()`	Large data, pipelines

Key concept: Lazy mode builds a query plan that gets optimized before execution. The optimizer applies predicate pushdown (filter early) and projection pushdown (select columns early).

模式	函数	执行时机	适用场景
即时	`read_csv()`	立即执行	小型数据、数据探索
延迟	`scan_csv()`	调用 `.collect()` 时执行	大型数据、数据管道

核心概念：延迟模式会先构建查询计划，在执行前完成优化。优化器会应用谓词下推（提前过滤）和投影下推（提前选择列）。

Core Operations

核心操作

Data Selection

数据选择

Operation	Purpose
`select()`	Choose columns
`filter()`	Choose rows by condition
`with_columns()`	Add/modify columns
`drop()`	Remove columns
`head(n)` / `tail(n)`	First/last n rows

操作	用途
`select()`	选择列
`filter()`	按条件筛选行
`with_columns()`	添加/修改列
`drop()`	删除列
`head(n)` / `tail(n)`	获取前n行/后n行

Aggregation

聚合操作

Operation	Purpose
`group_by().agg()`	Group and aggregate
`pivot()`	Reshape wide
`melt()`	Reshape long
`unique()`	Distinct values

操作	用途
`group_by().agg()`	分组并聚合
`pivot()`	宽表转换
`melt()`	长表转换
`unique()`	获取去重值

Joins

连接操作

Join Type	Description
inner	Matching rows only
left	All left + matching right
outer	All rows from both
cross	Cartesian product
semi	Left rows with match
anti	Left rows without match

连接类型	说明
inner	仅保留匹配的行
left	保留左表所有行及右表匹配行
outer	保留两张表的所有行
cross	笛卡尔积连接
semi	保留左表中存在匹配的行
anti	保留左表中无匹配的行

Expression API

表达式API

Key concept: Polars uses expressions (

pl.col()

) instead of indexing. Expressions are lazily evaluated and optimized.

核心概念：Polars使用表达式（

pl.col()

）而非索引方式。表达式会延迟计算并进行优化。

Common Expressions

常用表达式

Expression	Purpose
`pl.col("name")`	Reference column
`pl.lit(value)`	Literal value
`pl.all()`	All columns
`pl.exclude(...)`	All except

表达式	用途
`pl.col("name")`	引用列
`pl.lit(value)`	字面量值
`pl.all()`	所有列
`pl.exclude(...)`	排除指定列外的所有列

Expression Methods

表达式方法

Category	Methods
Aggregation	`.sum()` , `.mean()` , `.min()` , `.max()` , `.count()`
String	`.str.contains()` , `.str.replace()` , `.str.to_lowercase()`
DateTime	`.dt.year()` , `.dt.month()` , `.dt.day()`
Conditional	`.when().then().otherwise()`
Window	`.over()` , `.rolling_mean()` , `.shift()`

类别	方法
聚合	`.sum()` , `.mean()` , `.min()` , `.max()` , `.count()`
字符串	`.str.contains()` , `.str.replace()` , `.str.to_lowercase()`
日期时间	`.dt.year()` , `.dt.month()` , `.dt.day()`
条件判断	`.when().then().otherwise()`
窗口函数	`.over()` , `.rolling_mean()` , `.shift()`

Pandas Migration

Pandas迁移指南

Pandas	Polars
`df['col']`	`df.select('col')`
`df[df['col'] > 5]`	`df.filter(pl.col('col') > 5)`
`df['new'] = df['col'] * 2`	`df.with_columns((pl.col('col') * 2).alias('new'))`
`df.groupby('col').mean()`	`df.group_by('col').agg(pl.all().mean())`
`df.apply(func)`	`df.map_rows(func)` (avoid if possible)

Key concept: Polars prefers explicit operations over implicit indexing. Use

.alias()

to name computed columns.

Pandas	Polars
`df['col']`	`df.select('col')`
`df[df['col'] > 5]`	`df.filter(pl.col('col') > 5)`
`df['new'] = df['col'] * 2`	`df.with_columns((pl.col('col') * 2).alias('new'))`
`df.groupby('col').mean()`	`df.group_by('col').agg(pl.all().mean())`
`df.apply(func)`	`df.map_rows(func)` （尽可能避免使用）

核心概念：Polars更倾向于显式操作而非隐式索引。使用

.alias()

为计算列命名。

File I/O

文件读写

Format	Read	Write	Notes
CSV	`read_csv()` / `scan_csv()`	`write_csv()`	Human readable
Parquet	`read_parquet()` / `scan_parquet()`	`write_parquet()`	Fast, compressed
JSON	`read_json()` / `scan_ndjson()`	`write_json()`	Newline-delimited
IPC/Arrow	`read_ipc()` / `scan_ipc()`	`write_ipc()`	Zero-copy

Key concept: Use Parquet for performance. Use

scan_*

for large files to enable lazy optimization.

格式	读取	写入	说明
CSV	`read_csv()` / `scan_csv()`	`write_csv()`	人类可读
Parquet	`read_parquet()` / `scan_parquet()`	`write_parquet()`	高速、压缩存储
JSON	`read_json()` / `scan_ndjson()`	`write_json()`	换行分隔格式
IPC/Arrow	`read_ipc()` / `scan_ipc()`	`write_ipc()`	零拷贝

核心概念：追求性能时使用Parquet格式。处理大文件时使用

scan_*

方法以启用延迟优化。

Performance Tips

性能优化技巧

Tip	Why
Use lazy mode	Query optimization
Use Parquet	Column-oriented, compressed
Select columns early	Projection pushdown
Filter early	Predicate pushdown
Avoid Python UDFs	Breaks parallelism
Use expressions	Vectorized operations
Set dtypes on read	Avoid inference overhead

技巧	原因
使用延迟模式	实现查询优化
使用Parquet格式	列存储、压缩特性
提前选择列	投影下推优化
提前过滤数据	谓词下推优化
避免Python自定义函数（UDF）	会破坏并行执行
使用表达式	矢量化操作
读取时指定数据类型	避免类型推断开销

vs Alternatives

与其他工具对比

Tool	Best For	Limitations
Polars	1-100GB, speed critical	Must fit in RAM
Pandas	Small data, ecosystem	Slow, memory hungry
Dask	Larger than RAM	More complex API
Spark	Cluster computing	Infrastructure overhead
DuckDB	SQL interface	Different API style

工具	最佳适用场景	局限性
Polars	1-100GB数据集、对速度要求高	数据必须可放入内存
Pandas	小型数据、生态完善	速度慢、内存占用高
Dask	超出内存的数据集	API复杂度更高
Spark	集群计算	基础设施开销大
DuckDB	SQL接口需求	API风格差异大

Resources

参考资源

Docs: https://pola.rs/
User Guide: https://docs.pola.rs/user-guide/
Cookbook: https://docs.pola.rs/user-guide/misc/cookbook/

官方文档：https://pola.rs/
用户指南：https://docs.pola.rs/user-guide/
实用手册：https://docs.pola.rs/user-guide/misc/cookbook/