本文详解如何解决 pandas dataframe 含 pd.timestamp 列时，通过 csv 中转写入 bigquery 失败的问题——核心在于时间戳格式不兼容及加载配置缺失，需统一为 bigquery 支持的字符串格式并显式指定 schema 或数据选项。
在使用 Pandas + Google Cloud Storage（GCS）+ BigQuery 的 ETL 流程中，一个常见陷阱是：当 DataFrame 包含 pd.Timestamp 类型列（如 df['CURRENT_TS'] = pd.Timestamp.now()），后续导出为 CSV 并调用 load_table_from_uri() 加载至 BigQuery 时，会触发如下错误：
Invalid value for mode: TIMESTAMP is not a valid value
该错误并非源于 BigQuery 表结构本身，而是因为 CSV 是纯文本格式，无法保留 Python 或 Pandas 的原生类型信息；BigQuery 在自动推断 CSV 模式（schema）时，会将时间戳字符串误判为 STRING 类型，而当你在 LoadJobConfig 中显式设置某字段为 TIMESTAMP 模式（mode）时，BigQuery 会校验该字段是否满足其内部模式定义规则——但 CSV 解析器此时实际未识别出该列为时间类型，导致 mode: TIMESTAMP 配置与数据解析结果冲突，从而报错。
✅ 正确做法是：在导出前将时间戳标准化为 BigQuery 兼容的 ISO 格式字符串，并配合正确的加载配置：
import pandas as pd
from google.cloud import bigquery
# ✅ 正确：转换为 BigQuery 支持的 timestamp 字符串格式（微秒级精度）
df['CURRENT_TS'] = pd.Timestamp.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3] # 可选：截断至毫秒（BigQuery 默认支持微秒，但部分场景更稳）
# 导出为 CSV（注意：不保存索引，确保无额外列）
df.to_csv('gs://your-bucket/path/data.csv', index=False, header=True)
# 配置加载作业（关键！）
job_config = bigquery.LoadJobConfig(
source_format=bigquery.SourceFormat.CSV,
skip_leading_rows=1, # 跳过表头
autodetect=False, # ❗必须设为 False，避免自动推断失败
schema=[
bigquery.SchemaField("CURRENT_TS", "TIMESTAMP"), # 显式声明类型
# 其他字段...
],
# 可选：指定时间戳解析格式（若需自定义格式，但标准 ISO 不需要）
# time_partitioning=...,
)
client = bigquery.Client()
uri = "gs://your-bucket/path/data.csv"
table_id = "your_project.your_dataset.your_table"
load_job = client.load_table_from_uri(uri, table_id, job_config=job_config)
load_job.result() # 等待完成? 关键注意事项：
- strftime('%Y-%m-%d %H:%M:%S.%f') 生成形如 '2024-06-15 14:23:45.123456' 的字符串，BigQuery 可直接解析为 TIMESTAMP；
- 若只需毫秒精度（更常见），可用 [:-3] 截断微秒后三位，得到 '2024-06-15 14:23:45.123'；
- 绝对禁用 autodetect=True —— CSV 时间戳字符串默认被识别为 STRING，若 schema 中又声明为 TIMESTAMP，将引发模式冲突；
- 如需更高鲁棒性，建议跳过 CSV 中转，直接使用 to_gbq() 或 load_table_from_dataframe()（后者原生支持 pd.Timestamp，无需手动格式化）：
# 更推荐（免 CSV、免格式转换、自动类型映射） df.to_gbq( destination_table="your_dataset.your_table", project_id="your_project", if_exists="append" )
总结：Pandas → CSV → BigQuery 的链路中，时间戳必须“降维”为标准字符串，并辅以显式 schema 和关闭自动推断，才能绕过类型校验陷阱。优先考虑直连写入（load_table_from_dataframe / to_gbq）可大幅降低此类问题发生概率。
