Polars：基于结构体列连接Lazy DataFrame后collect触发Panic异常

问题重现 #

定义连接列join_on = ["INT_COL","STRING_COL"]，将两个Lazy DataFrame转换为包含结构体列pks（连接列组合）与Day0/Day1（其余列组合）的DataFrame后执行outer join，打印执行计划正常，但调用collect()时触发Panic异常，错误信息如下：

thread '<unnamed>' panicked at 'not implemented', D:\a\polars\polars\crates\polars-core\src\series\series_trait.rs:60:13
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

Traceback (most recent call last):
File "C:\Users\smruti\AppData\Roaming\Python\Python310\site-packages\polars\utils\deprecation.py", line 93, in wrapper
  return function(*args, **kwargs)
File "C:\Users\smruti\AppData\Roaming\Python\Python310\site-packages\polars\lazyframe\frame.py", line 1561, in collect
  return wrap_df(ldf.collect())
pyo3_runtime.PanicException: not implemented

相关代码：

join_on= ["INT_COL","STRING_COL"]
col_list = ["INT_COL","STRING_COL", "TINYINT_COL", "DECIMAL_COL" ...]

other_columns = [col for col in col_list if col not in join_on]

# 转换为含结构体列的Lazy DataFrame
src0_struct_df= src_0_lazy_df.select(pl.struct(join_on).alias("pks"),
pl.struct(other_columns).alias("Day0"))

src1_struct_df= src_1_lazy_df.select(pl.struct(join_on).alias("pks"),
pl.struct(other_columns).alias("Day1"))

# 执行连接
etl_activity = src0_struct_df.join(src1_struct_df, on="pks", how="outer")
print(etl_activity) # 正常输出执行计划
print(etl_activity.collect()) # 触发异常

原因分析 #

Polars对应报错的版本尚未实现基于结构体列的Outer Join操作。Lazy模式下仅生成逻辑执行计划，不会触发实际计算，因此print(etl_activity)能正常输出；但调用collect()时触发底层执行逻辑，遇到未实现的结构体列Outer Join路径，直接抛出Panic异常。

解决方案 #

绕过结构体列连接的限制，直接使用原始多列执行Outer Join，之后再将非连接列打包为结构体列，实现相同的最终效果。

修改后的代码示例（提前重命名列） #

join_on = ["INT_COL", "STRING_COL"]
col_list = ["INT_COL","STRING_COL", "TINYINT_COL", "DECIMAL_COL" ...]

other_columns = [col for col in col_list if col not in join_on]

# 给两侧非连接列添加前缀，避免join后列名冲突
src0_renamed = src_0_lazy_df.rename({col: f"Day0_{col}" for col in other_columns})
src1_renamed = src_1_lazy_df.rename({col: f"Day1_{col}" for col in other_columns})

# 直接使用原始连接列执行outer join
joined_df = src0_renamed.join(src1_renamed, on=join_on, how="outer")

# 将前缀匹配的列打包为结构体
etl_activity = joined_df.select(
    join_on,
    pl.struct([col for col in joined_df.columns if col.startswith("Day0_")]).alias("Day0"),
    pl.struct([col for col in joined_df.columns if col.startswith("Day1_")]).alias("Day1")
)

# 正常执行收集
print(etl_activity.collect())

另一种实现方式（利用join自动添加的后缀） #

如果不提前重命名列，Polars会自动为右表的重复列添加_right后缀，左表保留原名，可基于此打包结构体：

join_on = ["INT_COL", "STRING_COL"]
col_list = ["INT_COL","STRING_COL", "TINYINT_COL", "DECIMAL_COL" ...]

other_columns = [col for col in col_list if col not in join_on]

# 直接多列outer join
joined_df = src_0_lazy_df.join(src_1_lazy_df, on=join_on, how="outer")

# 打包左表非连接列和右表非连接列
etl_activity = joined_df.select(
    join_on,
    pl.struct(other_columns).alias("Day0"),
    pl.struct([f"{col}_right" for col in other_columns]).alias("Day1")
)

print(etl_activity.collect())

注意事项 #

若后续Polars版本更新支持了结构体列的Outer Join操作，原始代码可恢复正常使用，建议关注Polars官方更新日志。

内容的提问来源于stack exchange，提问作者Smruti Prakash Mohanty