Snowflake Plugin for Ask DataHub：搭建对话式分析的语义层与数据层
【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub
Ask DataHub 是 DataHub 内置的会话式 AI 助手（相关介绍见 Ask DataHub 指南），而Ask DataHub Plugins通过 Model Context Protocol（MCP） 将外部工具直接接入聊天界面，插件体系概览见 Ask DataHub Plugins 总览。本文聚焦其中的Snowflake Plugin：它把 Ask DataHub 连接到 Snowflake 托管的 MCP Server，让用户在聊天中直接获得基于真实数据的对话式分析能力。读完本文，你将掌握在 Snowflake 中创建 MCP Server 与 OAuth 安全集成、在 DataHub 中配置插件、为用户开通连接，以及常见故障的排查方法。
注意：Ask DataHub Plugins 目前处于Private Beta阶段。如需启用该功能，请联系你的 DataHub 客户支持代表。
为什么连接 Snowflake：语义层与数据层的分工
Snowflake Plugin 采用双栈架构：
- DataHub 充当语义层（Semantic Layer）——帮助 AI 找到正确的数据。Ask DataHub 基于元数据图谱工作，能够理解资产名称、描述、血缘关系、所有权、域、标签、术语表和样例值等信息（见 Ask DataHub 如何工作），从而判断用户问题应该命中哪些表。
- Snowflake 充当数据层（Data Layer）——让 AI 真正查询和分析数据。Ask DataHub 定位到目标表之后，由 Snowflake 执行 SQL 并返回结果。
启用 Snowflake Plugin 后，Ask DataHub 可以：
- 对话式分析（Conversational analytics）——用自然语言提问，得到由真实数据支撑的答案。DataHub 利用元数据（描述、所有权、血缘）找到正确的表，Snowflake 负责执行查询。无需额外的元数据或语义建模。
- 数据探索（Data exploration）——理解数据集结构、预览样例数据、检查列值，用于评估数据质量或判断某个数据集是否适合当前用例。
- 数据调试（Data debugging）——针对 DataHub assertions（断言）发现的数据问题，直接到源头检查实际数据：查看空值、重复值、异常值或新鲜度问题。
因为插件使用OAuth，每个用户使用自己的 Snowflake 凭证完成认证。用户只能看到自己被授权访问的数据——无需在 DataHub 中额外管理策略或授权（grants）。
示例提示词（Example prompts）：
- "Query the top 10 customers by revenue this quarter"（查询本季度收入前 10 的客户）
- "How many null values are in the email column of the customers table?"（customers 表 email 列有多少空值？）
- "Compare last month's sales to this month across regions"（按地区对比上月与本月销售额）
- "Show me 5 sample rows from the orders table"（展示 orders 表 5 行样例数据）
前置条件（Prerequisites）
配置 Snowflake Plugin 需要满足以下条件：
- 一个 Snowflake 账户，且拥有
ACCOUNTADMIN权限（或具备创建 MCP Server、安全集成（security integration）和授权角色（grant roles）的等效权限）； - 已启用 Ask DataHub Plugins 的 DataHub Cloud 实例；
- DataHub 中的平台管理员（Platform admin）权限，用于配置插件。
需要说明的是，插件配置入口（Settings > AI > Plugins）要求持有Manage Platform Settings权限，这一点与 插件总览文档 中的说明一致。
管理员设置（Admin Setup）
Snowflake Plugin 使用User OAuth认证——每个用户用自己的 Snowflake 账户完成认证。整个设置流程分为两部分：先在 Snowflake 侧创建 MCP Server 与 OAuth 安全集成，再在 DataHub 侧配置插件。插件的 OAuth 机制与插件总览中介绍的 User OAuth 认证类型 一致：管理员配置 OAuth Provider（客户端 ID、客户端密钥、授权 URL、令牌 URL、scopes），用户走标准 OAuth 登录流程完成连接。
第 1 步：在 Snowflake 中创建 MCP Server
在 Snowflake 中创建一个 MCP Server，并暴露你想要使用的工具。推荐从SYSTEM_EXECUTE_SQL开始，它允许 Ask DataHub 直接对仓库执行 SQL 查询：
| 工具类型（Tool Type） | 用途 |
|---|---|
SYSTEM_EXECUTE_SQL | 推荐使用。直接对数据仓库执行 SQL 查询。这是让插件发挥作用所需的最低限度工具。 |
CORTEX_ANALYST_MESSAGE | 基于 Cortex Analyst 语义视图 进行自然语言分析——即在原始 SQL 之上构建的一层精选 BI/分析层。 |
CORTEX_AGENT_RUN | 从 Ask DataHub 内部以子代理（sub-agent）方式调用 Cortex Agents。 |
Snowflake 还支持其他工具类型，且单个 MCP Server 中可以包含多个工具。
示例：创建一个同时包含 SQL 执行工具与 Cortex Analyst 语义视图的 Server：
USE ROLE ACCOUNTADMIN; USE DATABASE YOUR_DATABASE; USE SCHEMA YOUR_SCHEMA; CREATE OR REPLACE MCP SERVER YOUR_MCP_SERVER FROM SPECIFICATION $$ tools: - name: "execute_sql" type: "SYSTEM_EXECUTE_SQL" description: "Execute SQL queries against the data warehouse" title: "SQL Executor" - name: "revenue_analytics" type: "CORTEX_ANALYST_MESSAGE" identifier: "YOUR_DATABASE.YOUR_SCHEMA.REVENUE_SEMANTIC_VIEW" description: "Analytics over revenue and sales data" title: "Revenue Analytics" $$;:::note 一个 MCP Server 对应一个数据库 Snowflake MCP Server 被限定在单个数据库范围内。如果你需要 Ask DataHub 跨多个数据库查询，请为每个数据库分别创建一个独立的 MCP Server（以及对应的插件）。 :::
从实现角度看，这里连接的是 Snowflake 托管的 MCP Server，而 DataHub 的插件机制要求外部 MCP Server 支持Streamable HTTP transport（见 DataHub MCP Server 文档 中关于传输方式的说明）。DataHub 侧以 MCP 客户端身份消费 Snowflake 暴露的工具，这与 Snowflake 反向连接 DataHub MCP Server（Snowflake Cortex Agents 通过 External MCP Server 消费 DataHub 元数据）恰好构成镜像关系。
第 2 步：授予访问权限（Grant Access）
将 MCP Server 的 USAGE 权限授予需要使用它的角色：
GRANT USAGE ON DATABASE YOUR_DATABASE TO ROLE YOUR_ROLE; GRANT USAGE ON SCHEMA YOUR_DATABASE.YOUR_SCHEMA TO ROLE YOUR_ROLE; GRANT USAGE ON MCP SERVER YOUR_DATABASE.YOUR_SCHEMA.YOUR_MCP_SERVER TO ROLE YOUR_ROLE;注意这里需要分别对数据库、Schema 和 MCP Server 授予 USAGE。Snowflake 对未授权对象倾向于"静默隐藏"而非报错，如果后续出现"连接成功但看不到数据"的问题，优先检查这组授权是否完整。
第 3 步：创建 OAuth 安全集成（Security Integration）
创建一个安全集成，将 Snowflake 用作 OAuth Provider。需要启用刷新令牌（refresh tokens），并将重定向 URI 设置为你的 DataHub 实例的 OAuth 回调地址：
CREATE OR REPLACE SECURITY INTEGRATION YOUR_INTEGRATION_NAME TYPE = OAUTH ENABLED = TRUE OAUTH_CLIENT = CUSTOM OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' OAUTH_REDIRECT_URI = 'https://<your-datahub-url>/integrations/oauth/callback' OAUTH_ISSUE_REFRESH_TOKENS = TRUE OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;:::caution 回调 URL 必须精确匹配OAUTH_REDIRECT_URI必须与 DataHub 插件创建表单中显示的 OAuth Callback URL完全一致（例如https://your-org.acryl.io/integrations/oauth/callback）。你可以从第 5 步创建插件时的表单中直接复制该 URL。 :::
:::caution 刷新令牌必须开启 请确保OAUTH_ISSUE_REFRESH_TOKENS设为TRUE。如果没有刷新令牌，用户将需要频繁重新认证。 :::
OAUTH_REFRESH_TOKEN_VALIDITY = 7776000表示刷新令牌有效期 7776000 秒，即 90 天；你可以根据组织的安全策略调整该值。
第 4 步：收集认证详情（Collect Authentication Details）
运行以下查询，收集 DataHub 侧配置所需的信息。
OAuth 客户端凭据（OAuth Client Credentials）：
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('YOUR_INTEGRATION_NAME');该查询返回一个包含OAUTH_CLIENT_ID和OAUTH_CLIENT_SECRET的 JSON 对象。
MCP Server URL：
URL 遵循以下格式：
https://<account-url>/api/v2/databases/<DATABASE>/schemas/<SCHEMA>/mcp-servers/<SERVER_NAME>:::note 账户 URL 格式 URL 中账户定位符（account locator）部分的点（.）要用连字符（-）替代。例如，如果账户定位符是abc12345.us-east-1，URL 中应使用abc12345-us-east-1.snowflakecomputing.com。 :::
到这里，你应该已经拿到了 DataHub 配置所需的全部取值：
| 取值（Value） | 来源（Source） |
|---|---|
| MCP Server URL | 由账户 URL、数据库、Schema 和 Server 名称拼接而成（见上方格式） |
| Client ID | 来自SYSTEM$SHOW_OAUTH_CLIENT_SECRETS的输出 |
| Client Secret | 来自SYSTEM$SHOW_OAUTH_CLIENT_SECRETS的输出 |
第 5 步：在 DataHub 中创建插件（Create Plugin in DataHub）
- 在 DataHub 中导航到Settings > AI > Plugins
- 点击+ Create，选择Snowflake MCP
- 填写插件详情：
| 字段（Field） | 取值（Value） |
|---|---|
| Name | Snowflake |
| Description | 一段插件的描述 |
| MCP Server URL | 第 4 步得到的 URL |
| Client ID | 来自第 4 步 |
| Client Secret | 来自第 4 步 |
| Default Scopes | refresh_token session:role:<ROLE_NAME> |
:::warning 选对角色很关键session:role:<ROLE_NAME>这个 scope 决定了用户连接后以哪个 Snowflake 角色执行操作。请将<ROLE_NAME>替换为你第 2 步中授予 MCP Server 访问权限的角色（例如session:role:DATA_ANALYST）。如果省略该 scope，将使用用户的默认角色——而默认角色可能没有MCP Server 的访问权限。此外，每个用户必须在 Snowflake 中被授予该指定角色，且该角色不能出现在安全集成的 blocked roles 列表中（参见 故障排除）。 :::
4.（可选）添加Instructions for the AI Assistant（AI 助手指令），确保Enable for Ask DataHub处于开启状态，然后点击Create。
关于第 4 步中的可选指令：插件总览文档指出，Instructions for the AI Assistant字段会在插件处于激活状态时被注入 AI 上下文，用于引导 Ask DataHub 何时及如何使用该插件——例如"Use this plugin to query Snowflake when users ask about revenue or customer metrics."（见 插件总览）。配置完成后，还可以使用Test Connection在保存前验证 MCP Server 是否可达、凭据是否有效（见 插件总览）。
用户设置（User Setup）
管理员配置好插件后，普通用户即可为自己启用：
- 导航到Settings > My AI Settings
- 找到Snowflake插件，点击Connect
- 你将被重定向到 Snowflake 完成认证，随后自动返回 DataHub
更完整的说明（包括从聊天界面直接启用的方式）见 插件总览的用户设置章节。由于插件采用 User OAuth，每个用户都用自己的 Snowflake 账号登录，因此数据可见范围完全由用户在 Snowflake 侧的权限决定，DataHub 无需为此维护任何独立的授权策略。
插件启用后，其工具会在 Ask DataHub 对话中自动可用：AI 助手会在问题相关时自动调用这些工具。例如：
- "What are the most queried tables in Snowflake this month?"——DataHub 搜索 + Snowflake 查询
- 先由 DataHub 根据元数据（描述、所有权、血缘）定位正确的表，再由 Snowflake 执行查询并返回结果
故障排除（Troubleshooting）
用户无法登录 / OAuth 失败（Users can't log in / OAuth fails）
OAuth 安全集成可能正在阻止用户的角色。请确保你想要用户承担的角色不在blocked roles 列表中：
ALTER SECURITY INTEGRATION "YOUR_INTEGRATION_NAME" SET BLOCKED_ROLES_LIST = ();查询失败（Query failures）
- 确认用户的 Snowflake 角色对目标表拥有
SELECT权限 - 确认用户已被授予 MCP Server 的
USAGE权限 - 检查仓库（warehouse）是否在运行且未被挂起（suspended）
令牌过期（Token expiration）
如果用户被频繁要求重新认证，请确认：
- 安全集成上已启用刷新令牌（
OAUTH_ISSUE_REFRESH_TOKENS = TRUE）； OAUTH_REFRESH_TOKEN_VALIDITY设置为了合适的时长（例如上文的 7776000 秒 / 90 天）。
小结
Snowflake Plugin 让 Ask DataHub 从"只读元数据"升级为"直接分析真实数据"：DataHub 负责语义层（找对表），Snowflake 负责数据层（跑查询），而 User OAuth 让权限边界天然与 Snowflake 侧的角色体系对齐。整个配置链路可以概括为：在 Snowflake 创建 MCP Server（选工具）→ 授权角色 → 创建 OAuth 安全集成（开刷新令牌、配回调）→ 收集客户端凭据与 Server URL → 在 DataHub 填入表单并选择正确的session:rolescope → 用户自助 Connect 认证。若需同时启用其他数据源，可参考同目录下的 Databricks 插件指南 与 dbt Cloud 插件指南，它们遵循相同的插件配置框架。
【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
