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 ToolboxGoogle 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。它解决的是数据场景中非常典型的归因问题当某个业务指标如销售额、点击率发生变化时究竟是哪些维度如门店、城市、品类的组合贡献了大部分变化。从实现上看该工具的核心机制是依据用户的input_data表或查询与contribution_metric、is_test_col等参数拼接一条CREATE TEMP MODEL ... OPTIONS(MODEL_TYPE CONTRIBUTION_ANALYSIS, ...) AS input_data语句创建一个临时贡献度分析模型再执行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-L350LLM 调用时遵循这些约束。必填参数参数类型说明input_datastring包含测试组test与对照组control数据的输入来源可以是完整 BigQuery 表 ID如my-project.my_dataset.my_table也可以是返回数据的 SQL 查询contribution_metricstring待分析指标对应的列名或表达式支持三种形态见下文is_test_colstring标识行属于测试组还是控制组的列名该列必须是布尔类型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之一。可选参数参数类型默认值说明dimension_id_colsarray of strings无唯一标识每个维度的列名数组top_k_insights_by_apriori_supportinteger30按 apriori support 排序后返回的 Top 洞察数量pruning_methodstringPRUNE_REDUNDANT_INSIGHTS冗余洞察剪枝策略可选NO_PRUNING或PRUNE_REDUNDANT_INSIGHTS其中pruning_method在运行时会被统一转为大写校验仅接受NO_PRUNING与PRUNE_REDUNDANT_INSIGHTS两个值非法值会直接报错bigqueryanalyzecontribution.go#L179-L185。输入校验面向 LLM 生成参数的安全防线由于参数可能由 LLM 动态生成源码对每个会拼进 SQL 的参数都做了严格校验防止 SQL 注入相关校验函数定义在 internal/tools/bigquery/bigquerycommon/util.gocontribution_metric不允许包含单引号ValidContributionMetricParam见 util.go#L165-L167is_test_col与dimension_id_cols中的每个列名必须匹配[a-zA-Z_][a-zA-Z0-9_]*的合法 BigQuery 列名格式ValidColumnParam见 util.go#L160-L162input_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其核心流程分为两个阶段。第一阶段创建临时贡献度分析模型工具会生成一个唯一模型 IDcontribution_analysis_model_uuid见 bigqueryanalyzecontribution.go#L135并构造如下 DDLCREATE 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-toolbigquery-analyze-contribution标签便于在INFORMATION_SCHEMA.JOBS中追踪该工具产生的查询任务。第二阶段用 ML.GET_INSIGHTS 取出洞察模型创建完成后工具在同一个 BigQuery 会话中执行bigqueryanalyzecontribution.go#L286-L289SELECT * 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-L59writeMode对bigquery-analyze-contribution的影响allowed默认不施加任何特殊限制工具为单次调用创建新的 BigQuery 会话blocked同样不施加额外限制该工具本质为只读分析操作protected启用基于会话的执行工具在与其他使用同一源的工具共享的 BigQuery 会话内运行此时input_data可以是引用会话内临时资源如TEMP表的查询会话获取逻辑在 bigqueryanalyzecontribution.go#L226-L238protected模式下通过源的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.带数据边界的最小配置如果源配置了allowedDatasetsinput_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。参考字段表fieldtyperequireddescriptiontypestringtrue必须为bigquery-analyze-contributionsourcestringtrue工具所执行的源名称descriptionstringtrue传给 LLM 的工具描述预置配置仓库在 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 MODELML.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Toolbox 的 bigquery-analyze-contribution 工具：用 BigQuery 贡献度分析洞察指标变化根因
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 ToolboxGoogle 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。它解决的是数据场景中非常典型的归因问题当某个业务指标如销售额、点击率发生变化时究竟是哪些维度如门店、城市、品类的组合贡献了大部分变化。从实现上看该工具的核心机制是依据用户的input_data表或查询与contribution_metric、is_test_col等参数拼接一条CREATE TEMP MODEL ... OPTIONS(MODEL_TYPE CONTRIBUTION_ANALYSIS, ...) AS input_data语句创建一个临时贡献度分析模型再执行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-L350LLM 调用时遵循这些约束。必填参数参数类型说明input_datastring包含测试组test与对照组control数据的输入来源可以是完整 BigQuery 表 ID如my-project.my_dataset.my_table也可以是返回数据的 SQL 查询contribution_metricstring待分析指标对应的列名或表达式支持三种形态见下文is_test_colstring标识行属于测试组还是控制组的列名该列必须是布尔类型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之一。可选参数参数类型默认值说明dimension_id_colsarray of strings无唯一标识每个维度的列名数组top_k_insights_by_apriori_supportinteger30按 apriori support 排序后返回的 Top 洞察数量pruning_methodstringPRUNE_REDUNDANT_INSIGHTS冗余洞察剪枝策略可选NO_PRUNING或PRUNE_REDUNDANT_INSIGHTS其中pruning_method在运行时会被统一转为大写校验仅接受NO_PRUNING与PRUNE_REDUNDANT_INSIGHTS两个值非法值会直接报错bigqueryanalyzecontribution.go#L179-L185。输入校验面向 LLM 生成参数的安全防线由于参数可能由 LLM 动态生成源码对每个会拼进 SQL 的参数都做了严格校验防止 SQL 注入相关校验函数定义在 internal/tools/bigquery/bigquerycommon/util.gocontribution_metric不允许包含单引号ValidContributionMetricParam见 util.go#L165-L167is_test_col与dimension_id_cols中的每个列名必须匹配[a-zA-Z_][a-zA-Z0-9_]*的合法 BigQuery 列名格式ValidColumnParam见 util.go#L160-L162input_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其核心流程分为两个阶段。第一阶段创建临时贡献度分析模型工具会生成一个唯一模型 IDcontribution_analysis_model_uuid见 bigqueryanalyzecontribution.go#L135并构造如下 DDLCREATE 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-toolbigquery-analyze-contribution标签便于在INFORMATION_SCHEMA.JOBS中追踪该工具产生的查询任务。第二阶段用 ML.GET_INSIGHTS 取出洞察模型创建完成后工具在同一个 BigQuery 会话中执行bigqueryanalyzecontribution.go#L286-L289SELECT * 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-L59writeMode对bigquery-analyze-contribution的影响allowed默认不施加任何特殊限制工具为单次调用创建新的 BigQuery 会话blocked同样不施加额外限制该工具本质为只读分析操作protected启用基于会话的执行工具在与其他使用同一源的工具共享的 BigQuery 会话内运行此时input_data可以是引用会话内临时资源如TEMP表的查询会话获取逻辑在 bigqueryanalyzecontribution.go#L226-L238protected模式下通过源的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.带数据边界的最小配置如果源配置了allowedDatasetsinput_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。参考字段表fieldtyperequireddescriptiontypestringtrue必须为bigquery-analyze-contributionsourcestringtrue工具所执行的源名称descriptionstringtrue传给 LLM 的工具描述预置配置仓库在 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 MODELML.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考