Python Polars LazyFrame怎样查看查询计划

在 Polars 里把 DataFrame 转成 LazyFrame 后，代码只是先描述查询，真正的执行通常要等到 collect()。如果想知道 Polars 将怎样读取、过滤和选择列，不必先收集全部数据，直接查看查询计划即可。

官方地址：https://docs.pola.rs/

本文用一个小项目完成三件事：先打印按代码写出的未优化计划，再打印优化后的计划，最后根据需要输出逻辑或物理计划图。这样能快速看出过滤条件是否被推到扫描阶段，以及查询到底在哪一步才会执行。

先准备一个可观察的 LazyFrame 小项目

示例不依赖外部 CSV，直接用内存数据构造一个销售明细查询。查询先筛选已支付订单，再保留少量列，最后按地区汇总。重点不是业务结果，而是让计划里同时出现扫描、过滤、投影和聚合这些节点。

import polars as pl

# 构造一份小数据，让查询计划有过滤、选列和聚合三个明显阶段。
orders = pl.DataFrame({
    "region": ["华东", "华南", "华东", "华北"],
    "status": ["paid", "pending", "paid", "paid"],
    "amount": [120, 80, 200, 150],
    "customer_id": [101, 102, 103, 104],
})

# LazyFrame 只描述查询；这里还没有执行聚合。
query = (
    orders.lazy()
    .filter(pl.col("status") == "paid")
    .select(["region", "amount"])
    .group_by("region")
    .agg(pl.col("amount").sum().alias("total_amount"))
)

# explain 只返回计划文本，不会把最终结果收集成 DataFrame。
print(query.explain(optimized=False))
print(query.explain())

如果只想确认计划，不要把 collect() 写在查看计划之前。collect() 会物化结果，而 explain() 和 show_graph() 是观察 LazyFrame 的入口。

用 explain 对比未优化和优化后的查询计划

query.explain(optimized=False) 适合回答“我写下的操作顺序是什么”。默认的 query.explain() 则回答“优化器准备怎样执行这段查询”。两者都返回字符串，因此可以直接打印、写入调试日志，或在本地排查时保存到文件。

# 关闭优化，观察接近源码顺序的逻辑计划。
raw_plan = query.explain(optimized=False)
print("--- 未优化计划 ---")
print(raw_plan)

# 默认打开优化，观察优化器重排后的逻辑计划。
optimized_plan = query.explain()
print("--- 优化后计划 ---")
print(optimized_plan)

# 只在调试阶段保存文本，避免把完整计划混入正常业务输出。
with open("polars-query-plan.txt", "w", encoding="utf-8") as plan_file:
    plan_file.write(optimized_plan)

阅读时从底部的数据源节点向上看。对本例来说，优化后的计划可能把过滤条件贴近数据读取位置，并尽早裁剪不需要的列；具体节点文本会随 Polars 版本、数据源和查询表达式变化，所以不要把整段输出当成稳定接口。

排查性能时优先看三个问题：过滤是否尽早发生、是否读取了不需要的列、聚合前的数据量是否已经缩小。计划显示的是优化器的意图，不等于一次真实执行的耗时报告。

需要图形时使用 show_graph

文本计划适合放在终端或日志里，关系复杂时可以用 show_graph() 生成 Graphviz 图。默认是优化后的计划；调试优化前后差异时，分别传入 optimized=False 和默认值。

# 生成优化后的逻辑计划图；output_path 让图保存到文件。
query.show_graph(
    optimized=True,
    plan_stage="ir",
    output_path="polars-optimized-plan.png",
)

# 对照生成未优化计划图，便于定位优化器改变了哪些关系。
query.show_graph(
    optimized=False,
    plan_stage="ir",
    output_path="polars-raw-plan.png",
)

绘图前需要本机安装 Graphviz 并让它出现在 PATH 中。若只想取得 DOT 文本而不显示图，可以使用 raw_output=True，并且不要同时传入 show 或 output_path。

如果使用流式引擎，还可以把 plan_stage 设为 "physical"，观察更靠近实际执行的物理计划。普通排查建议先看 ir：它更容易解释过滤、投影和聚合之间的关系。

把计划查看放进验收清单

一个可复用的检查顺序是：先用 explain(optimized=False) 确认代码表达的意图，再用 explain() 看过滤和列裁剪是否提前，最后在确实需要时生成 show_graph() 图。这样既不会为了看计划而提前加载全部数据，也能把优化前后的差异留在代码评审记录中。

常见误区有三个：把 explain() 当成执行结果、把计划节点文本当成跨版本稳定格式、以及没有 Graphviz 时反复修改查询代码。前两者是概念边界，最后一个只是绘图依赖问题；文本计划仍然可以独立使用。

常见问题

Q：只看查询计划会读取全部数据吗？

A：通常不会。explain() 返回计划文本，show_graph() 构造计划图；真正物化结果的是 collect() 或其他执行入口。

Q：为什么优化前后的计划长得不一样？

A：优化器可能做谓词下推、投影下推和表达式简化。应关注数据读取、过滤和列选择的相对位置，不要依赖某一版的完整字符串格式。

总结：Python Polars 查看 LazyFrame 查询计划，最实用的组合是 explain(optimized=False) 看原始意图、explain() 看优化结果、show_graph() 看结构关系。先用文本定位问题，再按需生成图，最后用 collect() 执行查询。