BigQuery Streaming Insert出现Repeated record added outside of an array错误

BigQuery 流式插入与批量加载（你注释掉withMethod后默认走的写入模式）对嵌套重复字段的格式校验逻辑不同：

• 批量加载对数据格式的兼容性更强，会自动修正部分轻微的结构不匹配问题
• 流式插入对TableRow结构和表Schema的匹配要求更严格，REPEATED类型字段必须严格以数组格式传递，哪怕只有1个元素也不能用单个对象替代，否则就会抛出*Repeated record with name: XXXX added outside of an array.*报错

• 首先在DeadLettersHandler中新增日志，输出报错行对应的完整TableRow序列化结果，不要仅核查源JSON：很多时候源JSON结构正常，但数据处理过程中、或是TableRow序列化环节会把长度为1的重复字段自动转成单个对象，导致流式写入失败
• 核查你使用的Apache Beam SDK版本：2.40.0之前的SDK存在已知Bug，序列化TableRow时会自动将长度为1的REPEATED字段转为单个值，批量写入时BigQuery服务端会自动兼容，流式写入则会直接报错
• 确认withSchemaFromView传入的Schema在流式作业运行时和批量运行时完全一致，排除动态Schema更新不及时导致的字段模式不匹配问题

• 优先升级Apache Beam SDK到2.40.0及以上版本，该版本已修复TableRow序列化时重复字段自动降格的问题
• 若暂时无法升级SDK，修改withFormatFunction的逻辑：所有表结构中定义为REPEATED的字段，无论元素个数多少，都强制封装为List类型存入TableRow，禁止单个值直接赋值
• 若上述方案都不生效，可临时调整写入逻辑：先将所有数据以批量模式写入临时BigQuery表，再通过定时任务将临时表数据同步到目标表，规避流式插入的严格校验
• 配置死信表兜底：将流式插入失败的行先写入结构简单的死信表，后续通过批量作业同步死信数据到目标表，避免数据丢失

内容的提问来源于stack exchange，提问作者bunta