bigquery-optimization

BigQuery 优化工作流

署名

必读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读 使用情况署名。对于直接在终端中执行的命令（绝不要在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-optimization)" ，并将 agent-skills/1.0 (skill:bigquery-optimization) 添加到 User-Agent 标头中。

前提条件与环境设置

在执行优化分析、评估版本或应用 DDL 修改之前：

1. Google Cloud SDK：确保已安装并配置 Google Cloud SDK。

2. 项目选择：设置当前 Google Cloud 项目：

   gcloud config set project {project_id}
   

3. 启用 API：确保已启用 BigQuery 和 BigQuery Reservation API：

   gcloud services enable \
       bigquery.googleapis.com bigqueryreservation.googleapis.com
   

4. 身份验证：对环境进行身份验证：

   • CLI 工具和 bq 命令：gcloud auth login
   • SDK 和自动化：gcloud auth application-default login
   • 服务账号：设置 GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

5. 结算与 IAM 角色：

   • 确认 {project_id} 已关联有效的 Google Cloud 结算账号。
   • 确保具备适当的 IAM 角色：
     • roles/bigquery.admin 或 roles/bigquery.resourceAdmin： Reservation 和容量承诺管理。
     • roles/bigquery.dataEditor 或 roles/bigquery.admin：修改 表架构、分区、集群和存储计费模式。
     • roles/bigquery.jobUser：运行评估查询。

6. 安装配套技能： 此技能属于由 3 个支柱组成的运维套件（bigquery-observability、 bigquery-optimization、bigquery-troubleshooting）。如果环境中尚未安装任何配套技能，请安装完整套件：

   npx skills add google/skills --skill bigquery-observability --skill bigquery-optimization --skill bigquery-troubleshooting
   

   （如果未安装 bigquery-observability，请使用下方参考部分中直接提供的独立基线公式和查询模板。）

工作流

确定用户请求的优化重点，并遵循相关工作流：

• 遥测与可观测性基线： 对于直接原始用量遥测、INFORMATION_SCHEMA 查询和基线指标计算，请参阅 bigquery-observability (bigquery_observability)。如果当前环境中没有可用的 bigquery-observability 配套技能，则本技能及其参考指南中的所有优化指南、DDL 模板和决策模型均已完整自包含。
• 容量与版本建模： 评估将工作负载从按需迁移到 Editions 的成本效益，以及如何为活跃的 Edition 预留资源、基线承诺和自动扩缩上限合理配置规模。
  • 说明： 阅读 references/capacity_planning_editions.md，提供 BigQuery 内置建议界面的深度链接（例如 Slot Estimator），并指导用户进行界面导航：1. 前往 Slot Estimator 标签页；2. 选择“On-Demand”作为来源，以分析历史查询量；3. 查看 Cost-Optimized Recommendations 和 Slot Usage Chart。
• 表与存储优化： 从计费模式、物理布局和生命周期角度优化存储成本。
  • 计费架构： 阅读 references/storage_billing_models.md，了解如何评估总体压缩比（例如，美国地区的 >2:1 阈值），以建议使用物理或逻辑计费；同时指出，盈亏平衡比率取决于具体区域费率和定制企业合同。提供 TABLE_STORAGE 查询时，始终使用 WHERE table_schema = '{dataset_id}' 进行范围限定，使用区域数据集视图，并提醒用户，0 行结果表示区域不匹配或不存在原生表，而非没有可计费用量。
  • 分区与聚簇策略： 阅读 references/table_partitioning_clustering.md，生成可用于生产环境的 DDL 模板（CREATE TABLE、将未分区表迁移为 CTAS，以及修改聚簇规范），强制启用裁剪（require_partition_filter = true），并管理分区上限（每个表最多 10,000 个分区）。
  • 生命周期管理： 阅读 references/storage_lifecycle_management.md，找出非活跃数据，并精准设置分区过期时间（TTL）、数据集过期时间和时间旅行窗口缩减方案。
  • 加速结构： 阅读 references/search_indexes.md，判断何时应为 STRING 或 JSON 数据中的选择性查找建议搜索索引，编写 CREATE SEARCH INDEX DDL，并告知用户如何验证索引覆盖范围和使用情况。阅读 references/materialized_views.md，判断何时应为大型基表上的重复聚合或联接建议物化视图，编写 CREATE MATERIALIZED VIEW DDL，并告知用户如何验证智能调优是否使用了该视图。阅读 references/bi_engine.md，判断何时应为 BI 仪表板加速建议使用 BI Engine 或物化视图，诊断 BI Engine 回退至 PARTIAL 或 DISABLED 的原因（bi_engine_statistics），并将 BI Engine 与用于预联接或预聚合数据的物化视图结合使用。
• SQL 优化： 优化单条 SQL 查询，以减少 slot-time 和读取的数据量。
  • 说明： 遵循 references/sql_optimization.md 中的说明，向用户提供如何改写 SQL 查询以减少 slot-time 和读取的数据量的建议。

执行护栏

• 术语与成本表述： 绝不承诺或保证“降低成本”或“减少支出”。始终使用 “优化账单” 或 “提高成本效益” 来表述建议。
• 明确范围表述与区域解析： 始终在回复最开头说明目标 project_id 和 region，让用户立即了解正在评估的确切范围。遵循以下 3 级解析层次：
  1. 明确指定的区域： 使用用户提示中指定的区域（例如，europe-west1）。
  2. 根据上下文确定的区域： 根据上下文中提及的特定数据集或资源解析区域。
  3. 未指定时的默认值： 默认使用 us / region-us，明确说明假定使用默认值 us，并指示用户如果资源位于其他区域，则替换为相应区域。区域格式： 在 Cloud Console 深层链接中，直接使用区域标识符（例如，region=us、region=europe-west1）。在针对 INFORMATION_SCHEMA 的 SQL 查询中，使用区域数据集限定符（例如，region-us、region-europe-west1）。
• 零行结果防护： 如果使用 WHERE table_schema = '{dataset_id}' 查询 TABLE_STORAGE 时返回 0 行，请勿继续进行空结果或零用量评估。这可能表明数据集位于其他区域或没有原生表；请停止操作，并提示用户确认数据集所在的区域。
• 填入具体参数： 生成 URL 和 SQL 查询时，始终将已知的 project_id 和 region 值直接填入代码和链接。绝不保留字面量 {project_id} 或 {location} 占位符让用户手动修改。
• 禁止自主采购或财务变更： 绝不向用户提供可执行脚本（例如用于自主购买年度承诺、变更版本层级绑定或修改存储计费模式的 gcloud 或 bq Shell 命令，如 bq update --storage_billing_model=...）。始终指导用户通过 Cloud Console 界面手动购买承诺、变更预留项以及更新存储计费模式。