本文介绍如何在 Polars 中批量、非循环地过滤 DataFrame 行——基于另一 DataFrame 中多个子串对目标列进行部分匹配（如 SQL 的 LIKE '%pattern%'），避免逐行迭代，充分发挥 Polars 的向量化与并行计算优势。
本文介绍如何在 polars 中批量、非循环地过滤 dataframe 行——基于另一 dataframe 中多个子串对目标列进行部分匹配（如 sql 的 `like '%pattern%'`），避免逐行迭代，充分发挥 polars 的向量化与并行计算优势。
在数据预处理中，常需根据一组关键词（如黑名单前缀）从主表中剔除包含任意关键词的记录——例如删除所有文件名含 "skip" 或 "discard" 的行。SQL 可通过 EXISTS + LIKE 高效完成，而传统 Polars 实现若依赖 iter_rows() 循环调用 .filter()，不仅语法冗长，更会严重损害性能：每次 .filter() 触发一次全量扫描与副本创建，丧失惰性求值与多线程优化能力。
幸运的是，Polars 自 0.20.0 起提供了原生支持批量子串匹配的表达式方法：.str.contains_any()。它接受一个字符串列表（或 Series），对目标列执行向量化部分匹配（默认启用正则转义，安全处理特殊字符），返回布尔 Series，可直接用于 .filter()。
以下为完整实践示例：
import polars as pl
# 模拟原始数据
df_data = pl.DataFrame({
"filename": ["keep.txt", "skip.txt", "keep2.txt", "skip3.txt",
"discard.txt", "file3.txt", "discard2.txt", "file4.txt"],
"col2": ["bar", "foo", "zoom", "custom1", "custom2", "custom3", "custom4", "custom5"]
})
df_filter = pl.DataFrame({"skip": ["skip", "discard"]}) # 注意：去重非必需，contains_any 自动处理
# ✅ 推荐方案：一行代码，向量化执行
result = df_data.filter(
~pl.col("filename").str.contains_any(df_filter["skip"])
)
print(result)输出：
shape: (4, 2) ┌───────────┬─────────┐ │ filename ┆ col2 │ │ --- ┆ --- │ │ str ┆ str │ ╞═══════════╪═════════╡ │ keep.txt ┆ bar │ │ keep2.txt ┆ zoom │ │ file3.txt ┆ custom3 │ │ file4.txt ┆ custom5 │ └───────────┴─────────┘
关键说明与注意事项
自动转义保障安全性：.str.contains_any() 默认将输入字符串视为字面量（literal），内部自动转义正则元字符（如 .、*、?），无需手动调用 escape=True。若需正则功能，请改用 .str.contains() 配合 regex=True 和自定义模式。
性能对比显著：相比循环版（O(n×m) 时间复杂度，n=主表行数，m=过滤词数量），.contains_any() 底层调用高度优化的 Aho-Corasick 算法或 SIMD 加速字符串搜索，接近 O(n+m) 复杂度，且全程单次执行、零中间副本。
-
替代方案（兼容旧版本）：若使用 Polars < 0.20.0，可构建组合表达式：
patterns = df_filter["skip"].to_list() expr = pl.all_horizontal( ~pl.col("filename").str.contains(pat) for pat in patterns ) result = df_data.filter(expr)此方式虽避免显式循环，但仍需 Python 层展开生成表达式树，不如 .contains_any() 简洁高效。
-
扩展场景建议：
- 大小写不敏感：添加 strict=False 参数（如 .str.contains_any(..., strict=False)）；
- 仅匹配开头/结尾：改用 .str.starts_with_any() 或 .str.ends_with_any()；
- 结合其他条件：在 .filter() 中与其他布尔表达式用 &（且）、|（或）组合，例如 df.filter(条件1 & ~条件2)。
总之，.str.contains_any() 是 Polars 对标 SQL WHERE col NOT LIKE ANY(ARRAY['%skip%', '%discard%']) 的最佳实践。它将“客户端循环 + 多次过滤”的反模式，升级为“单次向量化扫描 + 原生算法加速”的专业范式——既提升代码可读性与可维护性，又确保大数据量下的线性扩展能力。
