mcpField
B
bigquery-slot-cost-optimizer

bigquery-slot-cost-optimizer

github.com/google数据与数据库21.6k1.2k 次安装今天更新
代码仓库

关于 bigquery-slot-cost-optimizer

为 AI Agent 和云工程师提供 BigQuery 诊断与优化流程，涵盖槽位使用、查询成本、资源争用及扫描问题，并配有遥测分析脚本和修复手册。

主要功能

  1. 01分析查询遥测与槽位时长
  2. 02识别槽位争用和排队
  3. 03检测笛卡尔积与行数膨胀
  4. 04定位未分区表扫描
  5. 05通过试运行验证查询

适用场景

  1. 01找出高成本 BigQuery 查询
  2. 02诊断慢查询与内存溢出
  3. 03调查槽位争用或排队
  4. 04排查缺少分区过滤的扫描

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill bigquery-slot-cost-optimizer

安装后在 Claude Code 中输入/bigquery-slot-cost-optimizer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
optimization_rules.md
remediation_playbooks.md
scripts/
slot_analyzer.py

详细介绍

BigQuery 槽位与成本优化器

此技能为 AI Agent 和云工程师提供操作启发式方法，用于分析 BigQuery 资源消耗、计算槽位小时数、识别槽位争用和排队、缓解笛卡尔连接，并优化未分区表扫描。

触发条件与意图映射

当用户提出以下请求时，启用此技能：

  • “优化 BigQuery 查询性能或减少槽位使用量”
  • “找出 BigQuery 中成本最高的查询”
  • “诊断 BigQuery 槽位争用或排队”
  • “修复运行缓慢的 BigQuery 作业或内存溢出”
  • “检测 BigQuery 中的笛卡尔连接或行数激增”
  • “识别未分区表扫描或缺失的分区筛选条件”

前置条件与环境设置

执行此技能前，请确保环境已配置必要的 SDK、权限和结算信息：

  1. Cloud SDK 和客户端库安装：

  2. 项目、结算与区域选择：

    • 设置活动项目：

      gcloud config set project <PROJECT_ID>

    • 重要：目标 Google Cloud 项目必须关联有效的 Cloud Billing 账号。

    • 区域选择：指定目标 BigQuery 数据集位置或执行区域，因为 BigQuery INFORMATION_SCHEMA 视图严格限定于特定区域（例如 region-us 或 region-eu 等多区域位置，或 region-us-central1 等单一区域位置）。查询错误的区域会返回空的作业遥测数据。通过 --region 传入匹配的区域（脚本会自动将 us-central1 等位置名称规范化为 region-us-central1）。有效的位置标识符请参阅 BigQuery 位置。

  3. 启用 API：

    • 在项目中启用 BigQuery API：

      gcloud services enable bigquery.googleapis.com

  4. 身份验证设置：

    • 对本地 gcloud 环境进行身份验证，并配置应用默认凭据（ADC）：

      gcloud auth login
gcloud auth application-default login

  5. IAM 角色与权限：

    • 执行主体至少需要以下 IAM 角色：
      • roles/bigquery.jobUser：授予运行查询和分析遥测数据的权限。
      • roles/bigquery.resourceViewer：授予对 INFORMATION_SCHEMA.JOBS_BY_PROJECT 中查询元数据和容量预留的只读访问权限。

  6. 定价参考：

    • 此技能中的成本估算仅供规划参考。运行 scripts/slot_analyzer.py 前，请先根据用户特定参数（例如目标区域、所选版本（Standard、Enterprise、Enterprise Plus）和承诺层级（Pay-as-you-go、1-year、3-year）），在运行时从官方 Google Cloud BigQuery 定价获取实时 BigQuery 费率（并参考 BigQuery 版本简介了解各版本功能）。通过 --ondemand-rate <USD_PER_TIB> 和 --slot-hour-rate <USD_PER_SLOT_HOUR> 显式传入运行时获取的费率。

诊断执行工作流

执行自动遥测数据提取

运行 scripts/slot_analyzer.py，从 INFORMATION_SCHEMA.JOBS_BY_PROJECT 提取并分析历史查询遥测数据，并传入针对相应区域、版本和承诺层级在运行时获取的定价费率：

# General analysis passing live regional pricing rates fetched from BigQuery pricing
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --days 7 \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table

# Output structured JSON for programmatically parsing recommendations
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --days 7 \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format json

# Offline verification mode using synthetic or extracted telemetry
python3 scripts/slot_analyzer.py --mock-data-file path/to/extracted_telemetry.json \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table

# Dry-run mode to inspect regional SQL query
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --region region-us --dry-run

运行 python3 scripts/slot_analyzer.py --help，查看所有支持的 CLI 标志、分析模式（--mode）以及必需的定价费率参数（每 TiB 的 --ondemand-rate 和每槽位小时的 --slot-hour-rate）。

指标解读与决策树

使用以下决策规则评估遥测输出。关键要求：使用以下决策树对查询问题分类后，必须立即对 references/remediation_playbooks.md 调用 view_file，以阅读并执行相应的修复手册（Rule SLOT-001、Rule JOIN-001 或 Rule PART-001），并在回复中包含所有必需的诊断 SQL 查询和 4 步检查清单。

[Query Telemetry Analyzed]
       |
       +---> If wait_ratio_avg > 0.40 OR slot_contention == TRUE
       |     --> Classify as slot contention and queueing (Rule SLOT-001)
       |     --> MANDATORY: Read Rule SLOT-001 in references/remediation_playbooks.md
       |
       +---> If shuffle_output_bytes_spilled > 0 OR records_written > 10 * records_read
       |     --> Classify as Cartesian join (Rule JOIN-001)
       |     --> MANDATORY: Read Rule JOIN-001 in references/remediation_playbooks.md
       |
       +---> If total_bytes_billed > 10 GB AND no date/partition filters
       |     --> Classify as unpartitioned scan (Rule PART-001)
       |     --> MANDATORY: Read Rule PART-001 in references/remediation_playbooks.md
       |
       +---> Otherwise
             --> Check BI Engine, search indexes, or materialized view opportunities
             --> MANDATORY: Read references/optimization_rules.md

修复手册和架构参考链接

为尽量减少 SKILL.md 中的令牌消耗，具体修复手册（Rule SLOT-001、Rule JOIN-001、Rule PART-001）、诊断 SQL 查询和 DDL 重写模式均存放在 references/ 中：

验证和确认协议

最终确定查询重写之前：

试运行验证

验证查询语法并计算预计扫描的字节数，而不会产生费用：

from google.cloud import bigquery
client = bigquery.Client()
job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)
query_job = client.query(optimized_sql, job_config=job_config)
print(f"Scanned bytes: {query_job.total_bytes_processed / (1024**3):.2f} GB")
离线和试运行验证

  • 离线模拟遥测验证：使用合成或提取的 JSON 遥测负载（--mock-data-file），离线验证启发式分类、槽位争用检测、笛卡尔连接识别和成本估算：

    python3 scripts/slot_analyzer.py --mock-data-file path/to/extracted_telemetry.json \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR> --format table

  • CLI 试运行检查：验证区域 SQL 查询的构造和脚本执行，不连接 BigQuery，也不产生费用：

    python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> --region region-us --dry-run

评论

支持 Markdown