本文详解如何使用 Polars 的 update() 方法完成“外连接式更新”：对左表中键匹配的行，用右表对应列值覆盖；对右表独有行则追加；同时支持自动识别键列（排除数值列），并可扩展保留右表新增字段。
本文详解如何使用 polars 的 `update()` 方法完成“外连接式更新”：对左表中键匹配的行，用右表对应列值覆盖；对右表独有行则追加；同时支持自动识别键列（排除数值列），并可扩展保留右表新增字段。
在数据整合场景中，常需将右表（如最新观测、修正值或增量数据）“智能合并”进左表（如主数据集）：既保留左表全部记录，又用右表中同键行的最新值更新左表对应字段，同时接纳右表独有的新记录。Polars 提供了语义清晰、性能高效的 update() 方法，专为此类需求设计——它本质是带值覆盖逻辑的全外连接（how="full"），但比手动 join + coalesce 更简洁、更安全。
✅ 推荐方案：使用 update() 实现“覆盖式外合并”
最直接的方式是调用 DataFrame.update()：
import polars as pl
left = pl.read_csv("left.csv")
right = pl.read_csv("right.csv")
# 自动提取用于匹配的列：仅保留字符串型（或业务主键）列，排除数值列（如 yield）
matching_columns = list(
set(left.columns) & set(right.columns)
- set(left.select(pl.col(pl.Float64)).columns)
)
# 执行更新：右表值覆盖左表同键行，右表独有行追加到底部
result = left.update(right, on=matching_columns, how="full")
print(result)✅ 输出即为期望结果（7 行，8CEB45v1 的 yield 被更新为 0.999，B1234/B1235 新增）：
shape: (7, 4) ┌────────────┬───────────┬───────────┬───────┐ │ track_name ┆ type ┆ yield ┆ group │ │ --- ┆ --- ┆ --- ┆ --- │ │ str ┆ str ┆ f64 ┆ str │ ╞════════════╪═══════════╪═══════════╪═══════╡ │ 8CEB45v1 ┆ corn ┆ 0.999 ┆ A │ │ A188v2 ┆ corn ┆ 0.86308 ┆ A │ │ B73v6 ┆ corn ┆ 0.326076 ┆ A │ │ CI6621v1 ┆ sweetcorn ┆ 0.0357792 ┆ A │ │ CML103v1 ┆ sweetcorn ┆ 0.510464 ┆ A │ │ B1234 ┆ pepper ┆ 1.0 ┆ B │ │ B1235 ┆ pepper ┆ 2.0 ┆ B │ └────────────┴───────────┴───────────┴───────┘
⚠️ 关键注意：不要将待更新的列（如
yield）包含在on参数中。on应仅指定唯一标识行的“键列”（如track_name,type,group），而update()会自动对其他同名列执行值覆盖。若错误地将yield加入on，会导致重复匹配（如示例中出现两行8CEB45v1），违背业务意图。
?️ 进阶场景：保留右表新增列（如 fruit）
update() 默认仅保留左右共有的列。若右表含左表没有的列（如 fruit），需手动实现等价逻辑：
# 假设 right 新增列 'fruit'
common_cols = set(left.columns) & set(right.columns)
key_cols = common_cols - set(left.select(pl.col(pl.NUMERIC_DTYPES)).columns) # 排除所有数值列
value_cols = common_cols - key_cols # 待更新的共用非键列
extra_cols = set(right.columns) - common_cols # 右表独有列
result = (
left.join(right, on=list(key_cols), how="full", coalesce=True)
.select(
*key_cols,
*[pl.coalesce(f"{c}_right", c).alias(c) for c in value_cols],
*extra_cols
)
)该方案通过 join(..., coalesce=True) 自动处理空值，并用 coalesce() 优先取右表值（{col}_right），完美复现 update() 的覆盖逻辑，同时显式保留右表新增字段。
? 总结与最佳实践
-
首选
update()：语义明确、代码简洁、性能优秀，适用于标准“覆盖+追加”场景。 -
智能推导键列：通过
pl.col(pl.String)或pl.col(pl.NUMERIC_DTYPES)动态筛选，避免硬编码，提升脚本鲁棒性。 -
警惕列类型误判：若业务主键为整数 ID，需改用
pl.Int64等精确类型过滤，而非笼统排除所有数值列。 -
扩展性考量：当需保留右表新增列时，手动
join + coalesce是当前最灵活方案；也可向 Polars 社区提交 Feature Request，推动update(keep_extra_columns=True)支持。
掌握此模式，即可高效、准确地完成 Polars 中的数据版本化合并任务。
