本文详解如何在 bigquery 标准 sql 的参数化查询中正确传递 python 字符串数组（如 `['cz', 'sk']`），并通过 `unnest(@param)` 实现多值匹配，避免仅返回首项的常见错误。关键在于参数结构、类型声明与 bigquery 客户端配置的严格一致性。
您遇到的问题——查询结果中仅返回 'CZ' 而缺失 'SK'——并非逻辑错误，而是 pandas-gbq 的 read_gbq() 对嵌套参数配置的支持存在限制。其底层 google-cloud-bigquery 客户端版本（尤其旧版）对 configuration 中 queryParameters 的解析不够健壮，容易忽略 arrayValues 的完整结构或误判参数类型，导致 UNNEST(@s) 实际只展开第一个元素。
✅ 正确做法是显式使用 google.cloud.bigquery.Client 构造查询作业，确保参数以标准、可验证的方式传入。以下是推荐的完整解决方案：
✅ 推荐写法：使用原生 BigQuery 客户端（稳定可靠）
from google.cloud import bigquery
import pandas as pd
PROJECT_ID = 'prj_id'
input_array = ['CZ', 'SK'] # 直接用 Python list，无需 numpy.array
client = bigquery.Client(project=PROJECT_ID)
query = """
SELECT country, ROUND(SUM(tvr_yr_month), 0) AS PublicSales
FROM `your_dataset.your_table` -- ⚠️ 替换为实际表名（原代码中为 ``，需补全）
WHERE country IN UNNEST(@countries)
GROUP BY country
"""
job_config = bigquery.QueryJobConfig(
query_parameters=[
bigquery.ArrayQueryParameter(
"countries", "STRING", input_array
)
]
)
query_job = client.query(query, job_config=job_config)
df = query_job.to_dataframe()
print(df)
# 输出示例：
# country PublicSales
# 0 CZ 1272308
# 1 SK 984562? 关键修正点说明
| 问题点 | 原代码缺陷 | 正确实践 |
|---|---|---|
| 参数构造方式 | 手动拼 query_config 字典，易格式错（如 arrayValues 结构不被 pandas-gbq 识别） | 使用 bigquery.ArrayQueryParameter 类，由 SDK 自动序列化为合规 JSON |
| 数组类型声明 | {'type': 'ARRAY', 'arrayType': {'type': 'STRING'}} 冗余且易出错 | bigquery.ArrayQueryParameter(..., "STRING", [...]) 隐式声明，语义清晰 |
| 表名占位符 | 查询中 FROM `` 为空，会导致语法错误（即使未报错也无数据） | 必须填写完整表标识符，如 `project.dataset.table` |
| 依赖库行为 | pd.io.gbq.read_gbq() 对复杂参数支持不稳定（尤其 v0.17.x 及更早） | 绕过 pandas-gbq，直连 google-cloud-bigquery Client，控制力更强 |
⚠️ 注意事项
- ❌ 不要使用 numpy.array 作为参数源：pandas-gbq 和 google-cloud-bigquery 均期望原生 Python list；numpy.array 可能引发类型转换异常。
- ✅ 确保 BigQuery 表中 country 列值与数组元素完全匹配（大小写敏感、无空格）。
- ✅ 若需处理空数组，添加前置校验：
if not input_array: raise ValueError("Input array cannot be empty") - ✅ 生产环境建议启用查询缓存与超时控制：
job_config.use_query_cache = True job_config.maximum_bytes_billed = 10**10 # 10 GB
? 总结
UNNEST(@param) 本身功能完备，问题根源在于客户端 SDK 的参数封装方式。放弃手动构造 configuration 字典，改用 ArrayQueryParameter 是最简、最稳、最符合 Google 官方实践的解法。 同时务必补全表名、使用原生列表、升级 google-cloud-bigquery>=3.0.0 以获得最佳兼容性。如此，多值参数将被完整展开，所有匹配行均会准确返回至 DataFrame。
