BigQuery 使用 Go 客户端库批量插入数据时，若部分行校验失败（如类型不匹配、空值违反非空约束等），Put() 会返回 *bigquery.PutMultiError，而非简单 panic；需显式类型断言并遍历各条失败记录的详细错误信息（含字段名、错误原因和具体消息），才能准确定位并修复数据问题。
bigquery 使用 go 客户端库批量插入数据时，若部分行校验失败（如类型不匹配、空值违反非空约束等），`put()` 会返回 `*bigquery.putmultierror`，而非简单 panic；需显式类型断言并遍历各条失败记录的详细错误信息（含字段名、错误原因和具体消息），才能准确定位并修复数据问题。
在使用 cloud.google.com/go/bigquery 进行批量写入时，Uploader.Put(ctx, inserts) 方法的设计是“尽力而为”（best-effort）：即使部分行因 schema 不兼容、类型转换失败或违反约束而被拒绝，整个调用仍可能成功返回 nil 错误——但实际并非如此。更常见的情况是，当至少一行插入失败时，Put() 会返回一个 *bigquery.PutMultiError 类型的错误，它封装了每一条失败记录对应的多个子错误（例如某字段类型不匹配、空值插入到 REQUIRED 字段等）。若未正确处理该类型，仅用 fmt.Printf("%v\n", err) 输出，将只能看到模糊的 "X row insertions failed" 提示，完全丢失关键调试信息。
正确的错误处理方式是进行类型断言，并逐层解析错误结构：
err := u.Put(ctx, inserts)
if err != nil {
if multiErr, ok := err.(bigquery.PutMultiError); ok {
fmt.Printf("Batch insertion failed for %d rows:\n", len(multiErr))
for i, rowErr := range multiErr {
fmt.Printf("→ Row %d failed with %d errors:\n", i+1, len(rowErr.Errors))
for _, detail := range rowErr.Errors {
fmt.Printf(" - Location: %q | Reason: %q | Message: %q\n",
detail.Location, detail.Reason, detail.Message)
}
}
} else {
// 非批量错误（如网络超时、权限不足、表不存在等）
log.Fatalf("Non-batch error occurred: %v", err)
}
}值得注意的是，PutMultiError 是一个切片类型（[]*bigquery.RowError），每个 RowError 又包含 Errors []googleapi.Error（来自底层 API），其中 Location 表示出错字段名，Reason 常为 "invalid"、"required" 或 "tooLarge"，而 Message 则给出人类可读的失败原因（如 "Cannot convert value to integer (bad value): foobar"）。
关键注意事项：
- ✅ 始终优先检查
err是否为bigquery.PutMultiError，再 fallback 到通用错误处理； - ✅ 不要假设所有行都使用相同 struct 类型就一定兼容 schema——BigQuery 对
NULL、嵌套重复字段、时间精度、字符串长度等有严格校验； - ✅ 在开发阶段建议开启
table.Uploader(bigquery.MaxUploadRetry(0))避免重试掩盖原始错误； - ✅ 对于高可靠性场景，可结合
bigquery.RowInsertionErrorPolicy{IgnoreUnknownValues: false}显式控制未知字段行为（默认为true，易导致静默丢弃）； - ✅ 生产环境应记录
Location+Message到可观测性系统，便于快速定位脏数据源头。
通过结构化解析 PutMultiError，你不再需要靠猜测或反复试错来修复插入失败问题——每一处 Message 都是精准的数据清洗指令。
