polars

Polars 是一个基于 Apache Arrow 构建的高性能 DataFrame 库，支持 Python 和 Rust，提供基于表达式的 API、惰性求值框架和高效的数据处理能力，适用于 ETL、数据分析、pandas 迁移和数据管道优化。

安装

安装当前稳定版本（本次刷新时验证的版本）：

uv pip install "polars==1.41.2"

仅在需要时安装可选集成：

uv pip install "polars[excel,database,fsspec,pandas,numpy]==1.41.2"

核心概念

表达式

表达式是 Polars 操作的基本构建块，描述对数据的转换，可组合、复用和优化。使用 pl.col("column_name") 引用列，链式调用方法构建复杂转换。表达式是惰性的，仅在上下文（select、with_columns、filter、group_by）中执行。

惰性求值与即时求值

即时（DataFrame）：操作立即执行，如 pl.read_csv("file.csv")。

惰性（LazyFrame）：操作构建查询计划，执行前进行优化，如 pl.scan_csv("file.csv")，最后通过 .collect() 执行优化后的查询。

适合使用惰性的场景：处理大数据集、复杂查询管道、只需要部分列/行、性能关键。惰性求值的好处包括自动查询优化、谓词下推、投影下推和并行执行。

常见操作

选择：df.select("name", "age")，支持表达式和正则模式匹配。
过滤：df.filter(pl.col("age") > 25)，支持多条件。
添加/修改列：df.with_columns(...)，所有列并行计算。
分组聚合：df.group_by("city").agg(...)，支持多分组键和条件聚合。

聚合与窗口函数

常用聚合函数包括 pl.len()、sum()、mean()、min()/max()、first()/last()。窗口函数通过 over() 在保留行数的同时应用聚合，映射策略有 group_to_rows（默认，保留原始行顺序）、explode（更快但分组行在一起）、join（创建列表列）。

数据 I/O

支持 CSV、Parquet、JSON、Excel、数据库（通过连接器）、云存储（S3、Azure、GCS）、Google BigQuery 以及多文件/分区文件。Parquet 推荐用于性能场景。

转换操作

连接：df1.join(df2, on="id", how="inner")，支持不同列名连接。
拼接：pl.concat([df1, df2], how="vertical"/"horizontal"/"diagonal")。
透视与逆透视：df.pivot(...) 和 df.unpivot(...)。

pandas 迁移

Polars 相比 pandas 有显著性能提升和更简洁的 API。关键差异：无索引（仅使用整数位置）、严格类型（无静默类型转换）、支持惰性求值、默认并行。常见操作映射：选择列 df["col"] → df.select("col")；过滤 df[df["col"] > 10] → df.filter(pl.col("col") > 10)；添加列 df.assign(x=...) → df.with_columns(x=...)；分组 df.groupby("col").agg(...) → df.group_by("col").agg(...)；窗口 df.groupby("col").transform(...) → df.with_columns(...).over("col")。

最佳实践

大数据集使用惰性求值：pl.scan_csv 而非 read_csv。
避免在热路径中使用 Python 函数，尽量使用表达式 API 以并行化。
超大数据的流式处理：lf.collect(engine="streaming")。
尽早选择所需列。
使用合适的数据类型：低基数字符串用 Categorical，合适的整数大小，时间数据用日期类型。
条件操作：pl.when(condition).then(value).otherwise(other_value)。
空值处理：fill_null、is_null、drop_nulls。

参考文档

本技能包含以下参考文档：core_concepts.md（表达式、惰性求值、类型系统）、operations.md（常见操作）、pandas_migration.md（迁移指南）、io_guide.md（数据 I/O）、transformations.md（连接、拼接、透视）、best_practices.md（性能优化）。

智能体操作流程

检查环境：确认 Python 环境和库版本，检查数据形状、类型和缺失值。
确定输入：从数据或用户确认格式、标识符和参数，不要猜测。
先运行小版本：在样本上运行，检查运行时间和内存。
执行完整任务。
验证结果：使用留出数据、固定随机种子和适当指标，检查泄漏，报告不确定性。
报告：说明运行内容（版本、命令、参数）、检查内容和仍不确定的部分。

异常处理

内存不足或执行缓慢：子采样、使用分块或惰性计算、减小模型大小，并告知用户。
安装版本中缺少函数、标志或端点：查阅已安装版本的文档，适配并告知用户，不要虚构 API。
输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

绝不捏造结果、参数、标识符、引用或统计数据。
绝不报告本次会话中未计算的指标。
版本特定细节可能过时，请对照已安装版本的官方文档确认。
涉及费用、共享 GPU、云配额、个人或患者数据、不可撤销操作前先询问。

技能介绍

安装