polars

Polars

默认原则

使用 Polars 处理数据。始终使用惰性 API：先构建完整查询，再通过一次 .collect() 执行，让 Polars 在读取任何数据之前优化计划。.collect() 在流式引擎上运行，按批次处理数据以减轻内存压力。不要收集中间结果：每次 .collect() 都会实例化数据并丢弃计划，因此之后的所有操作都要从头开始优化。急切执行的代码会跳过优化器，并做更多工作。

已在内存中的数据也不例外。 如果查询从 DataFrame 开始——例如函数参数、pl.from_pandas(pdf)、pl.DataFrame(...) 或之前调用 .collect() 的结果——请在第一个操作之前调用 .lazy()，并在末尾调用 .collect()。.lazy() 不会产生开销（它只是包装数据，不会复制数据），而且能将逐步执行的急切流水线转换为一个经过优化的计划。除非用户要求急切执行，否则都应这样做。

# start from a file
pl.scan_csv("data.csv").filter(...).collect()

# start from an existing DataFrame — wrap it first
df.lazy().filter(...).group_by(...).agg(...).collect()

# avoid: eager, step by step, nothing to optimize
df = pl.read_csv("data.csv")
df.filter(...).group_by(...).agg(...)

从问题到洞察

当用户提出数据相关问题（“上个季度哪个地区增长最快？”）时，目标是一次性给出正确答案：先用一个低成本步骤发现架构，再一次性编写完整查询。先阅读 references/insight-recipes.md：其中包含可直接套用的查询模式（前 k 项、期间环比、分布、时间序列、群组分析类问题），以及回答前应执行的合理性检查。

1. 先发现架构。切勿猜测列名或数据类型。

lf = pl.scan_csv("sales.csv")        # or scan_parquet / scan_ndjson
print(lf.collect_schema())           # names and dtypes, no data read
print(lf.head(5).collect())          # eyeball values, formats, dirt

2. 将问题转换为一个惰性链式调用，遵循下方的规范模式。将模糊术语映射为明确的定义，并在答案中说明（“增长 = 与上一季度相比的收入变化百分比”）。
3. 在扫描时处理脏数据，不要等到下游再处理： pl.scan_csv(path, null_values=["N/A", ""], try_parse_dates=True)。
4. 在回答前检查结果是否合理。
5. 用数字作答，而不只是提供代码。 先给出洞察，再展示支持数据的表格，并保留 LazyFrame，以便后续问题能扩展现有调用链，而不是重新构建。

核心规则

• 优先使用表达式，而非 Python 函数。 只有在不存在对应表达式时才使用 map_elements、map_batches 或 map_groups——而这种情况几乎不会发生。表达式在 Rust 中并行运行；Python UDF 会让每个值都经过解释器处理，并禁用优化。
• 尽早筛选。 将 filter() 放在 group_by()、join() 和 with_columns() 之前，这样后续每个步骤处理的数据都会更少。
• 一次上下文，一次操作调用一个表达式。 将所有表达式传给同一个 with_columns()；同一上下文中的表达式会并行运行，而在循环中重复调用会使它们串行执行。当同一操作适用于多个列时，应编写一个可扩展到整个架构的表达式，而不是每列写一个。使用 .name.suffix() / .name.prefix() 重命名扩展后的列组；.alias() 只为一个输出命名。选择器形式和注意事项：references/expressions.md。
• Polars 严格遵循类型。 不会隐式转换，也不允许混合类型的列。使用 .cast() 显式转换；使用 .cast(pl.Float64, strict=False) 可将无法解析的值转换为 null，而不是报错。字符串应使用 str.to_date() / str.to_datetime() 解析为日期和日期时间，不要使用 .cast()。
• 遵循警告——切勿屏蔽警告。 Polars 警告会在消息中指出确切的修复方法：PerformanceWarning 及 PolarsInefficientMapWarning 等子类会提示你使用 collect_schema()，或将 map_elements 调用改写为原生表达式。请落实更改；切勿使用 warnings.filterwarnings("ignore") 或 warnings.catch_warnings() 将其隐藏。

import polars.selectors as cs

# avoid: same operation, one expression per column
lf.with_columns([(pl.col(c) * 1.1).alias(f"{c}_adj") for c in ["a", "b", "c"]])

# prefer: one expression, expanded by the schema
lf.with_columns((pl.col("a", "b", "c") * 1.1).name.suffix("_adj"))
lf.with_columns(cs.numeric().fill_null(0))          # in place, same names

规范查询模式

按以下顺序构建查询。每个步骤都会先缩减数据，再进入下一步。

customers = pl.scan_csv("customers.csv")

result = (
    pl.scan_csv("orders.csv")                    # 1. scan, never read
    .filter(pl.col("year") == 2024)              # 2. filter early
    .join(customers, on="customer_id", how="left")   # 3. join filtered data
    .with_columns(                               # 4. add computed columns
        (pl.col("revenue") - pl.col("cost")).alias("profit")
    )
    .group_by("region")                          # 5. group
    .agg(                                        # 6. aggregate
        pl.col("profit").sum().alias("total_profit"),
        pl.col("profit").mean().alias("avg_profit"),
        pl.len().alias("count"),
    )
    .filter(pl.col("count") > 10)                # 7. filter groups
    .sort("total_profit", descending=True)       # 8. sort
    .select("region", "total_profit", "avg_profit")  # 9. final columns
    .collect()                                   # 10. execute once
)

SQL

Polars 也可以运行 SQL——pl.sql(...)、lf.sql(...)、pl.SQLContext——使用相同的惰性引擎，并编译为相同的优化计划。用户编写或询问 SQL，或者需要迁移 SQL 查询时，请使用 SQL；否则请编写表达式。编写 SQL 前，请阅读 references/sql.md，了解入口以及少数方言差异。

易错点

以下每一点都很容易出错。

• then()/otherwise() 中的字符串是列名，不是值。 pl.when(c).then("adult") 会读取名为 adult 的列（否则会引发 ColumnNotFoundError）。请将字面值包装起来：.then(pl.lit("adult"))。
• 空值比较会静默丢弃行。 filter(pl.col("v") > 2) 会排除空值，因为 null > 2 的结果是 null，即假值。如果应保留空值： (pl.col("v") > 2) | pl.col("v").is_null()。
• 使用 &、|、~，并在每个条件两侧加括号。 Python 的 and/or/not 用于表达式时会引发错误；不加括号时，运算符 优先级也会导致比较关系错误： (pl.col("a") > 1) & (pl.col("b") < 5)。
• 在 with_columns() 中使用裸聚合，会将全局值广播到每一行。 with_columns(pl.col("v").mean()) 会用总体平均值填充该列——不会报错。 添加 .over("group")，即可获取与每行对齐的组内值。
• 输出名称重复会引发 DuplicateError。 计算列会保留其源名称；select(pl.col("p"), pl.col("p") * 1.1) 会失败。 始终对派生列使用 .alias()——对于展开的表达式，也可使用 .name.suffix(...)，它会保留每个源名称。
• 正则表达式列选择需要 ^...$ 锚点。 pl.col("sales_.*") 会被 视为字面列名并引发 ColumnNotFoundError； pl.col("^sales_.*$") 则会展开。一次 col() 调用不能混合名称与 数据类型——请改用选择器。
• 联接默认不会匹配空值。 内联接中，带有空值键的行会被静默丢弃；如果应当匹配，请传入 nulls_equal=True。
• 联接和分组汇总不会保留行顺序。 如果结果顺序很重要，请以 .sort() 结束；或者传入 join(..., maintain_order="left")，以保留左侧数据框的顺序。

版本与 API 验证

编写不确定的方法调用前，请根据已安装的版本进行验证，不要依赖记忆。不要假设 Polars 中存在 pandas 风格的拼写：它没有索引、没有 iloc，也没有 groupby。对于 Polars 1.x，请先阅读 references/lazy-api.md 末尾的“On Polars 1.x”部分。

• 如果 polars-mcp 服务的工具可用，请使用它们： polars_search_api("filter") 可按关键词查找方法， polars_browse("Expr.str") 可浏览命名空间，而 polars_get_docstring("Expr.str.contains") 可获取准确的签名。
• 否则请获取文档： references/expressions.md 顶部将每种表达式类别映射到 https://docs.pola.rs 上对应的在线 URL。

何时加载参考资料

这些参考文件包含本文件中未涉及的详细信息。遇到以下任务时，编写代码前必须先阅读相应参考资料——如果参考资料涵盖了该任务，就不要凭记忆翻译或作答。每个文件都以 ## Contents 开头，便于跳转到相应章节。

• 将 pandas 转换为 Polars——必须先阅读 references/pandas-to-polars.md（篇幅很短）。其中介绍了本文件未涉及的 API 差异陷阱。
• 回答自然语言数据问题—— references/insight-recipes.md（参见上文“从问题到洞察”）。
• references/contexts.md——详细介绍 select、with_columns、 filter、group_by/agg、over（窗口映射策略）、sort 和 join 的行为。
• references/expressions.md——字符串、时间、列表、结构体、展开 和选择器语法；类型转换；空值处理；条件表达式；以及上文介绍的 fetch-map。
• references/lazy-api.md——脏数据的扫描选项、使用 explain() 检查查询计划、超出内存容量的数据和写入目标 （sink_parquet），以及 Polars 1.x 中的差异。
• references/sql.md——SQL 入口、将 SQL 与表达式混用、方言说明，以及 SQL 参考资料 fetch-map。