用途：通过 BigQuery REST API（bigquery.googleapis.com/bigquery/v2）用 curl 运行 SQL、检查作业、浏览数据集与表结构，无需 SDK。核心概念是作业：每次查询作为某个计费项目中的作业运行，项目不一定是数据所在项目。
主要能力：同步查询 jobs.query（一次 POST，超时内返回行）；异步 jobs.insert → jobs.get → jobs.getQueryResults（提交、轮询、分页），也用于目标表、BATCH 优先级及 load/extract/copy 作业；取消运行中作业；列出近期作业；列出数据集与数据集内表；获取表结构与大小；用 tabledata.list 免查询预览表行。
使用方式：请求带 Authorization: Bearer 头，环境变量 GCP_PROJECT 指定计费项目，BQ_TOKEN 由运行时注入（未设可填任意占位值，勿自行创建或刷新令牌）。随附脚本 scripts/bq_query.sh 会提交查询、轮询、分页并解码标量列的 f/v 编码；支持 --param NAME=TYPE:VALUE、--dry-run、--max-gb、--max-rows、--json，退出码 0 成功、1 失败、2 等待超时（默认 600 秒，作业 ID 在 stderr）。分页统一用 pageToken，但字段名不一：jobs.query、getQueryResults、tabledata.list 用 pageToken，datasets.list、tables.list、jobs.list 等用 nextPageToken；getQueryResults 还返回 totalRows 全量计数，不能作为停止条件。轮询 jobs.get 时需带上 location，否则非 US 数据集可能 404。
适用场景：临时用命令行直接查询与分析 BigQuery 数据、自动化脚本中提交批处理作业、免扫描成本地预览表数据、检查作业与数据集元数据。
限制：受项目级配额约束，交互式查询排队上限约 1000 个，多数方法约每用户每秒 100 请求，需退避重试而非紧凑轮询；429/403 的 rateLimitExceeded/quotaExceeded 可重试。401 表示凭据未配置，403 accessDenied 表示权限不足，404 常见于漏传 location 或引用错误，400 为 SQL 错误。作业状态 DONE 仍可能失败，须检查 status.errorResult。嵌套或重复列以原始 f/v JSON 返回，需自行用 jq 处理。数组/结构参数、目标表、写处置、BATCH 优先级及非查询作业需直接使用 jobs.insert。更多端点细节见 references/api.md。