本文介绍使用 Polars 的 int_ranges 与模运算结合 list.gather，以零拷贝、内存友好的方式实现嵌套列表的循环重复填充（repeat-by-cycle）和长度截断，避免 repeat_by 引发的索引溢出与 panic。
本文介绍使用 polars 的 `int_ranges` 与模运算结合 `list.gather`，以零拷贝、内存友好的方式实现嵌套列表的循环重复填充（repeat-by-cycle）和长度截断，避免 `repeat_by` 引发的索引溢出与 panic。
在处理时空序列、点云坐标或传感器采样数据时，常需将变长嵌套列表（如 List[Array[2]]）统一为固定长度——不足则循环重复元素（非简单复制末尾），超出则截断。Polars 原生不提供 repeat_cycle 类操作，但可通过索引调度优雅实现，且性能远优于 repeat_by + explode + head 组合。
核心思路是：生成目标长度的循环索引序列，再用 list.gather 批量查表。例如目标长度为 5，某行列表长度为 3，则索引序列为 [0,1,2,0,1]（即 range(5) % 3），再据此从原列表中 gather 元素。
以下为完整实现：
import polars as pl
# 示例数据（含嵌套 List[Array[f32, 2]]）
lf = pl.LazyFrame(
{
"points": [
[[1.0, 2.0]],
[[3.0, 4.0], [5.0, 6.0]],
[[7.0, 8.0], [9.0, 10.0], [11.0, 12.0]],
],
"other": ["foo", "bar", "baz"],
},
schema={
"points": pl.List(pl.Array(pl.Float32, 2)),
"other": pl.String,
},
)
target_length = 5
result = lf.with_columns(
pl.col("points").list.gather(
pl.int_ranges(target_length) % pl.col("points").list.len()
)
).collect()
print(result)
✅ 优势说明：
-
无中间爆炸：不调用
repeat_by或explode，避免因repeat_by内部构建超大索引数组导致u32索引溢出（如 400 万行 × 平均 4000 元素 → 索引数组达 160 亿，超出u32上限）； -
向量化高效：
int_ranges和%均为纯表达式计算，全程在 Polars 查询引擎内完成，无需 Python 层循环； -
语义清晰：
range(N) % len直观表达“循环取模”，比repeat_by + head更易维护。
⚠️ 注意事项：
- 若某行
points为空列表（len() == 0），% 0将报错。生产环境建议前置过滤或用pl.when(...).then(...).otherwise(...)处理空情况：idx_expr = pl.when(pl.col("points").list.len() == 0).then( pl.lit([]) # 返回空列表，保持类型一致 ).otherwise( pl.int_ranges(target_length) % pl.col("points").list.len() ) -
int_ranges要求 Polars ≥ 0.20.0；旧版本可改用pl.arange(0, target_length, eager=False)（注意 eager 参数）。
? 延伸技巧：若需「先截断再填充」（即优先保留前 min(len, target) 个，不足时循环补），当前方案已天然支持——gather 对越界索引默认静默忽略（null_on_oob=False 为默认），但此处因模运算保证索引始终合法，无需额外处理。
综上，基于 int_ranges + modulo + list.gather 的方案是 Polars 中处理循环填充/截断任务的推荐范式：简洁、健壮、高性能，且完美规避大宽表场景下的索引溢出陷阱。
