本文介绍如何在 Polars 中高效实现「按指定字符串列表精确过滤 + 严格按该列表顺序排序」，解决 search_sorted 无法直接用于自定义枚举序的常见误区，并提供基于 pl.Enum 的简洁、稳定、类型安全的解决方案。
本文介绍如何在 polars 中高效实现「按指定字符串列表精确过滤 + 严格按该列表顺序排序」，解决 `search_sorted` 无法直接用于自定义枚举序的常见误区，并提供基于 `pl.enum` 的简洁、稳定、类型安全的解决方案。
在 Polars 中，若需将 DataFrame 按用户给定的字符串列表（如 ['y', 'x', 'z']）先过滤出匹配行，再严格按该列表顺序排列结果，常见的误区是尝试复用 search_sorted —— 尽管其文档提及“list version”，但 search_sorted 的设计初衷是为有序查找（类似 NumPy 的 searchsorted），返回的是插入位置索引，并非排序键。直接将其用于 sort() 会导致逻辑错位：它不保证输出顺序与输入列表一致，尤其当列中存在重复值或列表未覆盖全集时，行为不可控且难以调试。
正确的做法是利用 Polars 内置的枚举类型（pl.Enum），它天然支持按预定义类别的顺序进行排序。pl.Enum(l) 将列转换为受限枚举类型，其内部顺序即为列表 l 的元素顺序；随后调用 .sort() 即可获得严格遵循该顺序的结果，且自动跳过不在 l 中的值（配合 filter(...is_in(l)) 可确保数据纯净）。
以下是推荐的实现：
import polars as pl
def filter_sort_explicit(df: pl.DataFrame, column: str, order_list: list) -> pl.DataFrame:
"""
过滤并按指定列表顺序排序 DataFrame。
Parameters:
-----------
df : pl.DataFrame
输入 DataFrame
column : str
用于过滤和排序的目标列名
order_list : list
定义排序优先级的值列表（顺序即排序顺序）
Returns:
--------
pl.DataFrame
过滤后按 order_list 严格排序的 DataFrame
"""
return (
df.filter(pl.col(column).is_in(order_list))
.with_columns(pl.col(column).cast(pl.Enum(order_list)))
.sort(column)
)
# 示例验证
df = pl.DataFrame({
"a": [1, 2, 3, 4],
"b": [6.0, 5.0, 4.0, 3.0],
"c": ["z", "x", "y", "x"], # 含重复值
})
for order in ['y', 'x', 'z'], ['z', 'x', 'y'], ['x', 'z'], ['y', 'x'], ['z', 'y']:
result = filter_sort_explicit(df, 'c', order)
assert result['c'].to_list() == order, f"Failed for {order}"
print(f"✓ {order} → {result['c'].to_list()}")✅ 优势说明：
-
语义清晰：
pl.Enum(order_list)明确表达了“按此顺序解释该列值”的业务意图； -
类型安全：Polars 在运行时校验值是否属于枚举域，非法值会报错（可配合
strict=False容错）； -
性能良好：枚举排序底层优化，比手动映射字典或
map_dict更高效； -
天然去重/保序：
filter(...is_in(...))确保只保留合法值，.sort()严格按枚举序排列，重复值按原出现顺序稳定排序（Polars 默认稳定排序）。
⚠️ 注意事项：
-
pl.Enum自 Polars ≥ 0.20.0 起稳定支持，旧版本请升级； - 若
order_list包含重复元素（如['x', 'x', 'y']），pl.Enum会去重并以首次出现为准，因此务必保证列表无冗余； - 如需处理缺失值（
null），建议在filter前添加.drop_nulls(column)或在is_in中显式包含None（注意：pl.Enum不支持None，需提前清洗）。
综上，cast(pl.Enum(...)).sort() 是 Polars 生态中表达「自定义离散顺序排序」最地道、可靠且可维护的方式，应作为标准实践替代对 search_sorted 的误用。
