企业官网建设流程全解析

MCP Toolbox 的 bigquery-analyze-contribution 工具：用 BigQuery 贡献度分析洞察指标变化根因

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

本指南围绕 MCP Toolbox（Google MCP Toolbox）内置的bigquery-analyze-contribution工具展开，讲解它如何通过创建临时的CONTRIBUTION_ANALYSIS模型并调用ML.GET_INSIGHTS，对多维数据进行贡献度分析（Contribution Analysis），找出导致关键指标变化的主要维度组合。读完本文，你将掌握该工具的 6 个核心参数及校验规则、底层 SQL 执行链路、writeMode与allowedDatasets对工具行为的影响，以及完整的 YAML 配置与可直接复用的示例 Prompt。

工具概述：让 LLM 回答"指标为什么变了"

bigquery-analyze-contribution是 MCP Toolbox 针对 BigQuery 提供的分析型工具之一（同系列的还有bigquery-conversational-analytics、bigquery-forecast等，参见 docs/en/integrations/bigquery/tools/_index.md）。它解决的是数据场景中非常典型的"归因"问题：当某个业务指标（如销售额、点击率）发生变化时，究竟是哪些维度（如门店、城市、品类）的组合贡献了大部分变化。

从实现上看，该工具的核心机制是：

1. 依据用户的input_data（表或查询）与contribution_metric、is_test_col等参数，拼接一条CREATE TEMP MODEL ... OPTIONS(MODEL_TYPE = 'CONTRIBUTION_ANALYSIS', ...) AS <input_data>语句，创建一个临时贡献度分析模型；
2. 再执行SELECT * FROM ML.GET_INSIGHTS(MODEL <model_id>)查询该模型，返回按 apriori support 排序的 Top 洞察（top contributors）。

两条 SQL 的执行链路、参数校验、会话（session）与数据集（dataset）限制逻辑，均可在源码 internal/tools/bigquery/bigqueryanalyzecontribution/bigqueryanalyzecontribution.go 中找到完整实现。

参数详解：6 个参数的语义、默认值与校验规则

工具共接收 6 个参数，其中 3 个必填、3 个可选。参数骨架由buildParams统一构建（见 bigqueryanalyzecontribution.go#L313-L350），LLM 调用时遵循这些约束。

必填参数

contribution_metric支持的三种表达式形态（源码 bigqueryanalyzecontribution.go#L324-L334 的参数描述中给出了完整定义）：

• SUM(metric_column_name)：可加总指标（summable metric），其中列必须为数值类型；
• SUM(numerator_metric_column_name)/SUM(denominator_metric_column_name)：可加总比率指标（summable ratio metric），分子分母列均为数值类型；
• SUM(metric_sum_column_name)/COUNT(DISTINCT categorical_column_name)：按类别可加总指标（summable by category metric），加总列必须是数值类型，类别列必须为BOOL、DATE、DATETIME、TIME、TIMESTAMP、STRING或INT64之一。

可选参数

其中pruning_method在运行时会被统一转为大写校验，仅接受NO_PRUNING与PRUNE_REDUNDANT_INSIGHTS两个值，非法值会直接报错（bigqueryanalyzecontribution.go#L179-L185）。

输入校验：面向 LLM 生成参数的安全防线

由于参数可能由 LLM 动态生成，源码对每个会拼进 SQL 的参数都做了严格校验，防止 SQL 注入（相关校验函数定义在 internal/tools/bigquery/bigquerycommon/util.go）：

• contribution_metric：不允许包含单引号（ValidContributionMetricParam，见 util.go#L165-L167）；
• is_test_col与dimension_id_cols中的每个列名：必须匹配[a-zA-Z_][a-zA-Z0-9_]*的合法 BigQuery 列名格式（ValidColumnParam，见 util.go#L160-L162）；
• input_data若为表 ID：必须是dataset.table或project.dataset.table形式（ValidTableID，见 util.go#L43-L45）。

这些校验在单元测试中有直接对应用例：dimension_id_cols传入dim1; drop table x、is_test_col传入is_test; drop table x、contribution_metric传入SUM('metric')均会被拒绝（见 bigqueryanalyzecontribution_test.go#L158-L183），可作为理解"为什么这些参数如此受限"的源码级证据。

底层原理：两条 SQL 语句完成一次贡献度分析

Invoke是工具的执行入口（bigqueryanalyzecontribution.go#L119），其核心流程分为两个阶段。

第一阶段：创建临时贡献度分析模型

工具会生成一个唯一模型 ID（contribution_analysis_model_<uuid>，见 bigqueryanalyzecontribution.go#L135），并构造如下 DDL：

CREATE TEMP MODEL contribution_analysis_model_<uuid> OPTIONS( MODEL_TYPE = 'CONTRIBUTION_ANALYSIS', CONTRIBUTION_METRIC = SUM(metric), IS_TEST_COL = is_test, DIMENSION_ID_COLS = [dim1, dim2], -- 可选 TOP_K_INSIGHTS_BY_APRIORI_SUPPORT = 30, -- 可选，默认 30 PRUNING_METHOD = 'PRUNE_REDUNDANT_INSIGHTS' -- 可选，默认值 ) AS <input_data>

其中<input_data>的组装逻辑（bigqueryanalyzecontribution.go#L187-L211）决定了参数两种写法的语义：

• 若input_data以SELECT或WITH开头，会被识别为查询，直接包一层括号作为AS (...)子查询来源；
• 否则被识别为表 ID，组装为SELECT * FROM `dataset.table`作为来源，并先做表 ID 格式校验。

创建模型的 Job 上还会打上mcp-toolbox-tool=bigquery-analyze-contribution标签，便于在INFORMATION_SCHEMA.JOBS中追踪该工具产生的查询任务。

第二阶段：用 ML.GET_INSIGHTS 取出洞察

模型创建完成后，工具在同一个 BigQuery 会话中执行（bigqueryanalyzecontribution.go#L286-L289）：

SELECT * FROM ML.GET_INSIGHTS(MODEL contribution_analysis_model_<uuid>)

由于模型是TEMP MODEL，查询必须携带session_id连接属性才能访问，工具会从上一阶段运行的 Job 统计信息中提取会话 ID 并注入该查询。返回结果即为按 apriori support 排名的 Top 洞察，直接作为工具的响应交给 LLM 组织成自然语言结论。

writeMode 对工具行为的影响：会话机制详解

工具的行为受其bigquery源上writeMode配置的影响。writeMode有三个取值（常量定义见 internal/sources/bigquery/bigquery.go#L52-L59）：

会话获取逻辑在 bigqueryanalyzecontribution.go#L226-L238：

• protected模式下，通过源的BigQuerySession()拿到共享会话（会话创建与 7 天生命周期管理实现在 bigquery.go#L375-L461），建模型查询携带该session_id；
• 非protected模式下，建模型查询设置CreateSession = true，由 BigQuery 为该次调用创建新会话。

两种模式下，ML.GET_INSIGHTS查询都会使用最终确定的会话 ID（来源会话或新建会话，见 bigqueryanalyzecontribution.go#L275-L284）。

需要注意：protected模式不允许与useClientOAuth: true同时使用（见 bigquery.go#L167-L173 的启动校验），因为在客户端 OAuth 下每次调用都会新建会话，无法保留会话内的临时数据。

allowedDatasets 限制：数据访问白名单的两层校验

源的allowedDatasets配置用于将工具可访问的数据集限制在白名单内，bigquery-analyze-contribution对input_data做了差异化校验（bigqueryanalyzecontribution.go#L195-L211）：

• 无allowedDatasets限制：input_data可使用任意表或查询；
• 配置了allowedDatasets：
  • 若input_data是表 ID：解析出project.dataset并检查其是否在白名单中（支持dataset.table与project.dataset.table两种写法，前者使用客户端默认项目）；
  • 若input_data是查询：先以DryRun = true提交建模型查询做干跑，从查询统计信息（QueryStatistics.ReferencedTables）中取出所有被引用的表，逐一核对数据集是否在白名单内，任何越界访问都会拒绝执行（实现见 bigqueryanalyzecontribution.go#L239-L260）。

干跑校验在测试中有专门覆盖：当查询引用unauthorized_dataset中的表时，工具返回query accesses dataset 'test-project.unauthorized_dataset', which is not in the allowed list错误（见 bigqueryanalyzecontribution_test.go#L248-L367）。

此外，buildParams会在配置了allowedDatasets时，把允许的数据集列表动态写入input_data参数的描述文本（bigqueryanalyzecontribution.go#L313-L321），让 LLM 在生成参数时就明确数据访问边界。

配置示例：从源到工具的完整 YAML

最小配置

在 MCP Toolbox 配置文件中声明一个名为contribution_analyzer的工具，指向名为my-bigquery-source的 BigQuery 源：

kind: tool name: contribution_analyzer type: bigquery-analyze-contribution source: my-bigquery-source description: Use this tool to run contribution analysis on a dataset in BigQuery.

带数据边界的最小配置

如果源配置了allowedDatasets，input_data的描述会自动带上白名单约束：

kind: source name: my-bigquery-source type: "bigquery" project: "my-project-id" allowedDatasets: - "my_dataset_1" - "other_project.my_dataset_2" --- kind: tool name: contribution_analyzer type: bigquery-analyze-contribution source: my-bigquery-source description: Use this tool to run contribution analysis on a dataset in BigQuery.

关于writeMode、allowedDatasets等源级字段的完整语义与注释示例，可进一步阅读 docs/en/integrations/bigquery/source.md。

参考字段表

预置配置

仓库在 internal/prebuiltconfigs/tools/bigquery.yaml 中内置了该工具的预置声明（名为analyze_contribution，描述为"Use this tool to analyze the contribution about changes to key metrics in multi-dimensional data"），并把它归入analytics工具组，与ask_data_insights（对话式分析）、forecast（时间序列预测）并列，供需要"为什么数据变了 / 未来如何变化"类能力的场景直接使用。

高级用法：示例 Prompt

使用该工具前，可参照 BigQuery 官方贡献度分析文档准备示例表（例如爱荷华州酒类销售聚合数据）。下面两个 Prompt 可直接用于调用已配置的工具：

• What drives the changes in sales in the tablebqml_tutorial.iowa_liquor_sales_sum_data? Use the project id myproject.
• Analyze the contribution for thetotal_salesmetric in the tablebqml_tutorial.iowa_liquor_sales_sum_data. The test group is identified by theis_testcolumn. The dimensions arestore_name,city,vendor_name,category_nameanditem_description.

第二个 Prompt 中，"测试组由is_test列标识"对应is_test_col参数（该列需为布尔类型），五个维度列对应dimension_id_cols参数，total_sales对应contribution_metric参数，LLM 会按参数协议自动完成映射。

小结

bigquery-analyze-contribution将 BigQuery 的贡献度分析能力封装为 LLM 可调用的 MCP 工具：通过CREATE TEMP MODEL+ML.GET_INSIGHTS两条 SQL 在共享会话内完成洞察挖掘，用严格的参数校验（列名、表 ID、单引号）防范注入风险，用writeMode: protected支持引用会话内临时资源的分析，并用allowedDatasets白名单加干跑校验守住数据访问边界。理解这些参数与限制，能帮助你更安全、更精准地让 Agent 回答"指标为何变化"这类归因问题。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox