PyArrow Table 怎么合并多个 ChunkedArray 以便连续读取

PyArrow Table 拼接多个批次后，每一列可能是由多个底层 Array 组成的 ChunkedArray。如果后续代码需要按连续列读取，可以调用 table.combine_chunks() 创建一张新表；它不会改写原表，而是把各列的块尽量合并为一个块。要注意，这一步可能产生新的内存分配，不能把它当成无成本的“整理”。

官方地址：https://arrow.apache.org/docs/python/

一、先确认每列的 ChunkedArray 布局

Table 的列不是简单的 Python 列表，而是按列保存的 ChunkedArray。由多个 RecordBatch 创建 Table，或用 pa.concat_tables 拼接表时，同一列可能保留多个块。块多不代表数据错误，它只是记录了数据进入表时的边界。

import pyarrow as pa

# 用两个批次构造一张表，模拟分区读取后的多块列布局
left = pa.table({"id": [1, 2], "score": [10, 20]})
right = pa.table({"id": [3, 4], "score": [30, 40]})
table = pa.concat_tables([left, right])

# 逐列观察块数量；块数量比 Table 的行数更能说明布局
for name in table.column_names:
    column = table[name]
    print(name, column.num_chunks, len(column))

这里的输出重点不是某个固定数字，而是判断哪些列的 num_chunks 大于 1。若下游只做过滤、投影或再次按批处理，多块布局通常可以保留；若要把列交给只接受单个 Array 的接口，再考虑合并。

二、用 Table.combine_chunks 创建连续读取表

确定需要连续布局后，直接在 Table 上调用 combine_chunks。官方 API 将每列的底层块拼接到新表中，原始 table 仍可保留，因此可以把合并后的表作为一个明确的读取阶段产物。

# 合并每列的块，返回新 Table；原 table 不会被原地修改
combined = table.combine_chunks()

# 用块数量确认合并效果，并继续使用列名访问数据
for name in combined.column_names:
    column = combined[name]
    print(name, column.num_chunks, column.to_pylist())

对普通数值列和字符串列，常见结果是每列变成一个块。不要把“连续”理解成所有类型永远只有一个块：官方说明指出，为了避免二进制列的缓冲区溢出，某些列仍可能保留多个块。读取逻辑应以实际的 num_chunks 为准。

三、把内存开销纳入合并决策

合并的收益是减少下游遍历块的复杂度，代价则是为新布局分配缓冲区。可以先记录原表和结果表的缓冲区规模，再结合业务处理峰值做决定。get_total_buffer_size() 统计的是表引用到的缓冲区总大小；如果缓冲区被部分引用，它可能高估实际使用量，所以它更适合做相对比较，而不是精确的峰值证明。

# 比较布局变化和缓冲区规模；这不是进程峰值监控
before = table.get_total_buffer_size()
combined = table.combine_chunks()
after = combined.get_total_buffer_size()

print({
    "before_bytes": before,
    "after_bytes": after,
    "chunks_after": {
        name: combined[name].num_chunks
        for name in combined.column_names
    },
})

如果原表还要继续参与其他任务，合并期间可能同时存在原始缓冲区和新缓冲区。大文件处理应把合并放在稳定边界，例如单个分区完成后，或明确准备进入需要连续列的下游阶段，而不是每追加一小批数据就调用一次。

四、根据读取场景决定何时不合并

以下情况通常不必立即合并：数据仍在持续追加；下游本身支持 ChunkedArray；任务按 RecordBatch 分页处理；或者表很大而连续布局并不能带来可衡量的收益。保留块边界还能让处理过程更接近原始批次，减少一次全表复制。

相反，如果准备把一张稳定的表交给只接受单个 Array 的计算步骤，或者后续要反复顺序扫描同一列，合并一次再复用结果更合理。做判断时同时看三件事：列块数量是否明显、下游是否真的需要连续 Array、合并时的内存余量是否足够。

相关问题

combine_chunks 会修改原来的 Table 吗？

不会。它返回一张新的 Table；调用方仍可保留原表，但需要把返回值赋给新变量。

为什么合并后二进制列仍可能有多个块？

为了避免单个二进制缓冲区超过可接受的大小，合并操作可能保留多个块。不要用“每列必须一个块”作为通用断言。