用途
consomme 用于在 BigQuery 中进行数据分析，涵盖数据集探索、查询编写与仪表盘构建。它在用户询问数据、指标、趋势或模式且数据位于 BigQuery 时使用，也用于基于查询结果构建交互式 HTML 仪表盘，以及在向利益相关者分享前验证分析结果。它是一个分析方法论技能，而不是用于编写应用程序代码中查询 BQ 的客户端库。纯基础设施任务（创建数据集、管理 IAM）也不适用，应直接使用 GCP 控制台或 CLI。
五阶段工作流
每次分析都遵循五个阶段，各阶段映射到相应工具：
- DISCOVER（发现）：查找相关表和数据集，工具为 search_catalog、list_dataset_ids、list_table_ids。
- UNDERSTAND（理解）：了解模式、数据形态和质量，工具为 get_dataset_info、get_table_info、execute_sql。
- ANALYZE（分析）：查询、聚合、建模、检验显著性，工具为 execute_sql、forecast、analyze_contribution。
- VALIDATE（验证）：分享前检查结果，工具为 execute_sql（交叉核对、抽查）。
- PRESENT（呈现）：可视化与沟通，将上述阶段结果转为图表、仪表盘、表格。
除非用户指定了具体表，否则从 Discover 开始。绝不跳过 Understand——分析前始终先做数据剖析。在 Analyze 阶段比较分组或细分时，需检查观察到的差异是否具有统计意义。
主要能力
search_catalog 提供跨表、视图、模型、例程和连接的语义搜索，prompt 参数为自然语言描述，适合用户以概念而非表名描述数据时使用。list_dataset_ids 列出项目中所有数据集，list_table_ids 列出特定数据集中的所有表。get_dataset_info 获取数据集级元数据，get_table_info 获取表元数据（含模式、分区配置、聚簇字段、行数）。
execute_sql 是核心工具，用于执行 SQL 语句，承担剖析、分析和验证。成本意识方面：BigQuery 按扫描字节计费，编写昂贵查询前应使用 dry_run: true 预览成本，始终按分区列过滤，避免 SELECT *，大表上用 APPROX_COUNT_DISTINCT() 替代 COUNT(DISTINCT)。结果集管理方面：探索性查询始终加 LIMIT（20–50），先聚合再选择，大表用聚合查询而非导出原始行。
forecast 用于时间序列预测。必填参数：history_data（返回时间序列的 SQL 查询）、timestamp_col、data_col、horizon（默认 10）；可选 id_cols 用于并行序列。前提条件：数据须有真实时间维度，历史数据点至少为 horizon 的 2 倍，须预聚合为每时间周期一行，并排除当前不完整周期。
analyze_contribution 用于分析哪些维度对关键指标变化贡献最大，适用于用户问“为什么 X 变化了”等场景。必填参数：input_data（返回两个群体的 SQL 查询）、contribution_metric、is_test_col；可选 dimension_id_cols。工具返回排序后的贡献者。对于二元 0/1 响应列，使用 SUM(column) 作为指标，并将维度列转为 STRING。
使用方式与配置
Gemini CLI：通过 gemini auth login 自动认证，设置 BIGQUERY_PROJECT 环境变量为 GCP 项目 ID。Claude Code / Amp：需要配置 BigQuery MCP 服务器（如 bq-toolbox），使用应用默认凭据或服务账号凭据，项目在 MCP 服务器配置中设置。权限：读取需 roles/bigquery.user，创建表/视图还需 roles/bigquery.dataEditor。
对于约 5K 行以下的 Google Sheets，可使用 /consomme-sheets <url> 直接在上下文中分析，无需 BigQuery 访问，采用相同的剖析方法论（形态检测、质量评估、分布）但作用于 CSV 数据，需要 mise MCP 服务器来获取表格。
数据形态检测与 SQL 参考
剖析前先识别数据形态：多表、ID 列、外键关系 → 数据仓库；单宽表、多列、列名是问题或代码 → 调查问卷；日期/时间戳列驱动分析 → 时间序列。应询问用户确认，不要假设。混合形态很常见。BigQuery 专用函数、性能技巧和常见分析模式（窗口函数、CTE、同期群留存、漏斗、去重）见 references/sql-reference.md，编写或审查任何 SQL 时都应阅读。关键要点：BigQuery 没有 ILIKE，使用 LOWER(col) LIKE '%pattern%'；使用 DATE_TRUNC(col, MONTH) 而非 DATE_TRUNC('month', col)；大表基数用 APPROX_COUNT_DISTINCT()；始终按分区列过滤；避免 SELECT *。
验证框架
分享任何分析前需完成交付前 QA 清单，涵盖数据质量（源表验证、数据新鲜度、时间序列缺口、空值率、双重计数、WHERE 子句正确性）、计算检查（GROUP BY 完整性、比率分母、日期比较周期长度、JOIN 类型、指标定义一致）、合理性（数值范围、异常跳变、与已知来源匹配、边界情况）和呈现（图表从零开始、精度与格式、标题说明洞察、注明局限与假设）。
常见陷阱包括：连接爆炸（多对多连接静默放大行数）、幸存者偏差、周期不完整比较、分母漂移、平均值的平均、时区错配、细分中的选择偏差。结果合理性检查涵盖量级检查、交叉验证技术（用两种方法计算同一指标、抽查记录、对比基准、反向推算、边界检查）和统计有效性（每组样本量 n ≥ 30、检验显著性、多重比较校正）。需要注意的红旗包括：任何指标环比变化超过 50% 且无明显原因、恰好整数、恰好 0% 或 100% 的比率、完美确认假设的结果、跨时间或细分完全相同的值。
每个非平凡分析都应记录：问题、来源（表与截止日期）、定义、方法论、假设、局限、关键发现。
可视化
提供图表选择指南：时间趋势用折线图，类别比较用垂直条形图，排序用水平条形图，部分-整体用堆叠条形图，分布用直方图，两变量相关性用散点图，多变量相关性用热图，流程用桑基图或漏斗图，绩效对比目标用子弹图，多 KPI 用小倍数图。不建议使用饼图（除非少于 6 个类别）、3D 图表（绝不使用）、双轴图表（谨慎使用）、多类别堆叠条形图。
展示目标方面：Chart.js HTML 适合快速分析与一次性探索，智能体可完全自主构建；Google Sheets + BQ 连接器适合非技术用户，智能体创建 BQ 视图后由用户在 Sheets 中连接（Data → Data connectors → BigQuery → 选择 project.dataset.view_name）；Looker Studio 适合生产级仪表盘，无 API，智能体准备数据层，用户在 GUI 中构建。Chart.js HTML 仪表盘的详细模式见 references/dashboard-patterns.md。
限制
该技能本身是方法论与工具使用指南。实际使用依赖配置好的 BigQuery MCP 服务器或 Gemini CLI 认证，以及相应的 BigQuery 权限。forecast 与 analyze_contribution 的使用各有前提条件。Looker Studio 无 API，智能体无法直接构建。具体收费、价格等信息资料中暂未提供。