使用PyArrow将CSV转换为带字典编码的Apache Arrow IPC文件时遇字典替换报错，如何修复？

这个报错的原因很明确：当你开启auto_dict_encode=True时，PyArrow会为每个单独的批次自动生成字典编码，但Arrow IPC文件格式要求同一个字段的字典在所有数据批次中必须是唯一且一致的，不能在不同批次里替换字典，所以就触发了这个ArrowInvalid错误。

下面给出两种针对性的修复方案，分别适配小文件和大文件场景：

方案1：适合小文件 - 先全量加载为Table再写入 #

如果你的CSV文件不大，能完全加载到内存里，最简单的方式是先把整个CSV读取成一个Arrow Table，再写入IPC文件。这样PyArrow会为整个数据集生成统一的字典，不会出现批次间字典不一致的问题：

import pyarrow as pa
import pyarrow.csv as csv

file = "./in.csv"
arrowFile = "./out.arrow"

# 先读取整个CSV为Table，开启自动字典编码
convert_options = csv.ConvertOptions(auto_dict_encode=True)
table = csv.read_csv(file, convert_options=convert_options)

# 将Table写入IPC文件
with pa.OSFile(arrowFile, 'wb') as f:
    with pa.RecordBatchFileWriter(f, table.schema) as writer:
        writer.write_table(table)

方案2：适合大文件 - 先预扫描生成全局字典 #

如果文件太大，没法一次性加载到内存，就需要先预扫描CSV，收集目标字段的所有唯一值，提前定义好全局的字典类型，再用这个固定类型读取并写入：

步骤1：预扫描CSV，收集唯一值并构建全局字典类型 #

import pyarrow as pa
import pyarrow.csv as csv

file = "./in.csv"

# 先获取原始CSV的schema，识别需要处理的字符串字段
raw_table = csv.read_csv(file, convert_options=csv.ConvertOptions(include_columns=None))
raw_schema = raw_table.schema

# 遍历所有字符串字段，收集每个字段的全局唯一值，生成字典类型
global_dict_types = {}
for field in raw_schema:
    if pa.types.is_string(field.type):
        # 提取当前字段的所有唯一值
        unique_values = raw_table[field.name].unique().to_pylist()
        # 构建该字段的全局字典类型（用int32作为字典索引类型）
        global_dict_types[field.name] = pa.dictionary(pa.int32(), field.type, ordered=False)

# 替换原始schema中的字符串字段为对应的全局字典类型
new_schema_fields = []
for field in raw_schema:
    if field.name in global_dict_types:
        new_schema_fields.append(pa.field(field.name, global_dict_types[field.name]))
    else:
        new_schema_fields.append(field)
fixed_schema = pa.schema(new_schema_fields)

步骤2：用固定字典类型读取并写入IPC文件 #

arrowFile = "./out.arrow"

# 定义转换选项，强制使用预构建的全局字典schema
convert_options = csv.ConvertOptions()
convert_options.set_schema(fixed_schema)

with pa.OSFile(arrowFile, 'wb') as arrow:
    with csv.open_csv(file, convert_options=convert_options) as reader:
        with pa.RecordBatchFileWriter(arrow, reader.schema) as writer:
            for batch in reader:
                writer.write_batch(batch)

补充优化建议 #

• 你可以通过ConvertOptions的dict_encode_max_cardinality参数，只对唯一值数量低于阈值的字段做字典编码，避免对高基数字段（比如用户ID、订单号）做字典编码，浪费存储和计算资源。
• 对于超大型文件，也可以用pyarrow.dataset API简化流程，它能自动处理批次间的类型一致性：

import pyarrow.dataset as ds

file = "./in.csv"
arrowFile = "./out.arrow"

dataset = ds.dataset(file, format="csv")
# 扫描时指定自动字典编码规则
scanner = dataset.scanner(
    convert_options=csv.ConvertOptions(auto_dict_encode=True, dict_encode_max_cardinality=1000)
)
# 转换为Table后写入IPC
scanner.to_table().write_ipc(arrowFile)

备注：内容来源于stack exchange，提问作者Jay Askren