PyArrow compute.cast 溢出时怎么选择安全转换策略

PyArrow 的 compute.cast 默认按安全转换处理：遇到目标类型装不下的整数、时间精度损失或其他不安全转换时，优先保留错误，而不是把异常值悄悄截断。真正需要“放宽”时，先确认损失边界，再在 CastOptions 中只打开对应开关。

官方地址：https://arrow.apache.org/docs/python/generated/pyarrow.compute.cast.html

这篇只讨论 safe 参数、整数溢出和不兼容值的处理边界，不把“能转过去”误认为“转换结果可靠”。

一、先记住三条选择规则

• 默认转换或显式写 safe=True：适合数据质量优先的导入、清洗和接口边界。
• 显式写 safe=False：只适合已经证明输入范围、截断结果和下游协议都可接受的场景。
• 需要只放开某一种风险时：使用 CastOptions，不要把所有安全检查一并关闭。

target_type、safe 和 options 是两种调用方式：前两者描述目标类型和总的安全策略，options 则把风险拆成更细的开关。两种方式不要混用，否则会得到参数冲突。

二、默认安全转换怎样拦住整数溢出

例如输入是 int16，目标是 int8。127 在目标范围内，而 128 和 -129 超出范围。安全模式会把这类数据当成转换失败处理，调用方可以记录坏行、退回宽类型，或在清洗后重新转换。

import pyarrow as pa
import pyarrow.compute as pc

# 构造一个包含边界内外数值的输入列，便于说明安全转换的判定范围
values = pa.array([120, 127, 128, -129, None], type=pa.int16())

try:
    # safe=True 会检查目标 int8 能否容纳每个非空值
    result = pc.cast(values, target_type=pa.int8(), safe=True)
except pa.ArrowInvalid as exc:
    # 生产代码应保留原始列或坏行信息，避免把错误值静默写入下游
    print(f"转换被拒绝：{exc}")

这里的重点不是捕获异常后继续写入，而是把“溢出”变成显式的数据质量信号。若输入来自 CSV、Parquet 或外部接口，通常应该先统计越界值，再决定是修正源数据还是提高目标类型宽度。

三、什么时候可以使用 safe=False

safe=False 表示调用方接受不安全转换。它不是“让 PyArrow 自动找到最接近结果”的智能修复开关；当数据超出目标类型范围时，结果可能发生截断或环绕，不能把它当作异常值清洗方案。

import pyarrow as pa
import pyarrow.compute as pc

# 只有在协议已经规定允许窄化，并且上游已完成范围检查时才考虑该路径
values = pa.array([10, 20, 30], type=pa.int16())
result = pc.cast(values, target_type=pa.int8(), safe=False)

# 输出类型应立即检查，后续写入按 int8 的语义处理
print(result.type)

更稳妥的工程规则是：如果你不能写出目标类型的最小值、最大值和越界处理方式，就不要使用 safe=False。例如订单金额、计数器和外部 ID 一般不能因为“暂时能装下”就直接窄化。

四、用 CastOptions 只放开已知风险

批处理场景经常不是单一的整数溢出：时间戳可能只允许降精度，十进制可能允许截去尾数，文本列可能需要明确处理无效 UTF-8。此时用 CastOptions 能把决策写在代码里，而不是用一个总开关掩盖所有风险。

import pyarrow as pa
import pyarrow.compute as pc

# 只允许整数溢出这一类已知损失，其他安全检查仍保持开启
options = pc.CastOptions(
    target_type=pa.int8(),
    allow_int_overflow=True,
)

values = pa.array([1, 2, 3], type=pa.int16())
result = pc.cast(values, options=options)
print(result.type)

需要注意，options 与 target_type、safe 不是叠加关系。已经创建 CastOptions 后，把目标类型和各项允许条件都放进 options；不要再写 pc.cast(values, pa.int8(), safe=True, options=options)。

五、批量导入时怎样落地选择

可以把转换策略固定成下面这张小决策表：

如果是 Table，也可以按目标 schema 做整体转换，但安全策略仍然存在：字段名和顺序需要匹配，列中任何一个不兼容值都可能让整体转换失败。对不可信的宽表，先按列探测范围再转换，通常比一次性关闭安全检查更容易定位问题。

六、常见误区与排查顺序

1. 把溢出当成显示问题：先确认输入类型、目标类型和实际极值，再决定是否改变 schema。
2. 同时传 safe 和 options：二选一；需要细粒度控制就只传 options。
3. 用 safe=False 代替数据清洗：它只改变转换约束，不会告诉你哪些行不可信。
4. 只看转换成功：还要检查输出类型、精度变化和下游读取方是否接受该类型。

一句话总结：默认安全转换负责守住边界，CastOptions 负责表达“只允许哪一种损失”，safe=False 只应出现在范围和协议都已经明确的窄化路径上。

相关问题

safe=True 是不是只检查整数溢出？

不是。它表示检查溢出或其他不安全转换；时间截断、时间范围、十进制或浮点精度等风险也应按目标类型和 CastOptions 的具体开关判断。

能不能同时传 target_type 和 CastOptions？

不建议。把目标类型放入 CastOptions，再通过 options 调用，避免参数来源分散和冲突。

转换失败时应该扩大类型还是清洗数据？

看字段语义。计数和标识类字段通常扩大目标类型；确实存在脏值的导入列，则应隔离越界行并保留原始值，不能用静默截断替代清洗。