当使用 cloud.google.com/go/bigquery 批量插入数据时，若部分行失败，Put() 仅返回模糊的“X row insertions failed”提示；需通过类型断言捕获 bigquery.PutMultiError 获取每条失败记录的具体列名、错误消息和原因。
当使用 `cloud.google.com/go/bigquery` 批量插入数据时，若部分行失败，`put()` 仅返回模糊的“x row insertions failed”提示；需通过类型断言捕获 `bigquery.putmultierror` 获取每条失败记录的具体列名、错误消息和原因。
在 Go 中调用 BigQuery 的 Uploader.Put() 方法进行批量写入时，常见误区是将错误视为单一异常而忽略其结构化特性。实际上，Put() 在部分行写入失败时不会直接 panic 或返回标准 error，而是返回一个实现了 error 接口的 *bigquery.PutMultiError 类型——它封装了每个失败行的详细上下文，包括出错字段（Location）、人类可读的错误描述（Message）以及标准化错误码（Reason，如 "invalid"、"required"、"duplicate" 等）。
以下为推荐的健壮错误处理模式：
err := u.Put(ctx, inserts)
if err != nil {
if multiErr, ok := err.(bigquery.PutMultiError); ok {
fmt.Printf("共 %d 行插入失败:\n", len(multiErr))
for i, rowErr := range multiErr {
fmt.Printf("第 %d 行失败:\n", i+1)
for _, fieldErr := range rowErr.Errors {
fmt.Printf(" ▪ 字段 '%s': %s (原因: %s)\n",
fieldErr.Location,
fieldErr.Message,
fieldErr.Reason)
}
}
} else {
// 非批量错误（如网络超时、认证失败、表不存在等）
log.Fatalf("全局写入失败: %v", err)
}
}⚠️ 关键注意事项：
-
PutMultiError是切片类型（[]*bigquery.PutMultiErrorRow），每个元素对应一条插入失败的记录；而rowErr.Errors是该行内多个字段校验失败的集合（例如某行同时存在类型错误和空值缺失）。 - 错误中的
Location值严格匹配 Schema 中定义的字段名（区分大小写），可用于精准定位数据结构问题。 - 常见
Reason值包括："invalid"（类型转换失败，如字符串"foobar"写入INT64列）、"required"（非空字段为nil）、"duplicate"（违反唯一约束，需配合INSERT ... ON CONFLICT等高级策略）、"tooLarge"（单行超 10MB 限制）。 - 若未显式指定
Schema（如代码中StructSaver{Struct: insert, Schema: schema}），BigQuery 会尝试自动推断，但易导致隐式类型不匹配——强烈建议始终显式传入预定义 Schema。
✅ 最佳实践补充：
- 插入前对敏感字段做轻量级预校验（如正则校验邮箱、范围检查数值）；
- 对高吞吐场景，考虑启用
u.JobIDPrefix = "my-job-"便于追踪后台作业； - 使用
u.IgnoreUnknownValues = true可跳过 Schema 中未定义的字段（谨慎开启，避免数据丢失）； - 单次
Put()最多支持 10,000 行，超量请分批并控制并发（建议 ≤ 10 并发上传器）。
通过结构化解析 PutMultiError，你不再需要靠日志盲猜或反复试错，而是能精准定位每一处数据与 Schema 的不兼容点，大幅提升 BigQuery 数据管道的可观测性与稳定性。
