BigQuery Go 客户端默认将结构体字段推断为 REQUIRED 模式，导致空值被写为默认零值（如空字符串），而非 NULL；解决方法是改用 bigquery.Null* 类型（如 NullString、NullInt64）并配合结构体标签显式控制模式。
bigquery go 客户端默认将结构体字段推断为 required 模式，导致空值被写为默认零值（如空字符串），而非 null；解决方法是改用 `bigquery.null*` 类型（如 `nullstring`、`nullint64`）并配合结构体标签显式控制模式。
在 BigQuery 中，字段的模式（Mode） 决定了其是否允许 NULL 值：REQUIRED 表示不可为空，NULLABLE（默认）表示可为空。而 Go SDK 的 bigquery.InferSchema() 方法对基础类型（如 string、int）默认推断为 REQUIRED，这与 BigQuery 的语义不一致——尤其当业务逻辑中某些字段本应可选时，会导致数据失真（例如 "" 覆盖了语义上的“未提供”）。
✅ 正确做法是：使用 cloud.google.com/go/bigquery 提供的专用空值封装类型，它们内置 Valid 标志位，能准确表达“有值”或“无值（NULL）”两种状态，并被 InferSchema 自动识别为 NULLABLE 模式。
以下是改造后的结构体示例：
import "cloud.google.com/go/bigquery"
type Stats struct {
Name bigquery.NullString `bigquery:"name"`
LastName bigquery.NullInt64 `bigquery:"last_name"`
PhoneNumber bigquery.NullString `bigquery:"phone_number"`
}此时调用 bigquery.InferSchema(Stats{}) 将生成如下 Schema（JSON 表示）：
[
{"name": "name", "type": "STRING", "mode": "NULLABLE"},
{"name": "last_name", "type": "INT64", "mode": "NULLABLE"},
{"name": "phone_number", "type": "STRING", "mode": "NULLABLE"}
]插入数据时，需显式设置 Valid 字段来控制是否写入 NULL：
rows := []*Stats{
{
Name: bigquery.NullString{StringVal: "testA", Valid: true},
LastName: bigquery.NullInt64{Int64Val: 0, Valid: false}, // → NULL in BigQuery
PhoneNumber: bigquery.NullString{StringVal: "", Valid: false}, // → NULL, not ""
},
}
u := table.Uploader()
if err := u.Put(ctx, rows); err != nil {
log.Fatal(err)
}⚠️ 注意事项：
- 不要混用基础类型与
Null*类型在同一结构体中——InferSchema会为string推断REQUIRED，为NullString推断NULLABLE，混合使用易引发模式不一致； -
Null*类型的Valid: false对应 BigQuery 的NULL；Valid: true且值为零值（如""或0）则写入该零值（非 NULL）； - 若需兼容 JSON 反序列化，可为
Null*字段添加自定义UnmarshalJSON方法，或使用第三方库（如github.com/mitchellh/mapstructure）辅助转换； - 对于嵌套结构或数组字段，仍需结合
bigquery.Schema手动构建以精确控制REPEATED和RECORD模式。
总结：*用 `bigquery.Null` 替代原生 Go 类型，是 Go 生态中与 BigQuery NULL 语义对齐的标准实践**。它不仅解决了空值写入问题，也使数据契约更清晰、可维护性更强。
