Set up docs MCP将 ClickHouse Cloud 连接到您的数据目录，以访问其中的开放表格式表。您可以在 数据源 UI 中配置连接。若要通过 SQL 进行设置，请在您常用的 SQL 编辑器中使用 DataLakeCatalog 数据库引擎。
连接后，目录中的表会显示在 SQL 控制台中您指定的数据库下。您可以使用标准 ClickHouse SQL 查询这些表，将其与 MergeTree 表进行联接，并将其作为 materialized views 的源表。
前置条件
连接目录前，请确认以下事项：
- 服务权限。 你需要具备
control-plane:service:manage权限，才能访问数据源页面并添加目录。 - 正在运行的服务。 如果服务处于空闲状态，请在连接或查看关联的目录前，通过数据源页面或服务设置页面将其唤醒。
- 目录凭据。 打开弹出面板前，请准备好目录类型所需的连接信息。每个目录使用的字段和身份验证方式不同——请参阅下方的添加目录连接。
连接您的目录
打开数据目录弹出面板
- 在左侧导航栏中选择 数据源。
- 如果尚未设置任何数据源，请点击 + 添加目录；否则，点击 添加数据源 > 添加数据湖目录。
- 在 连接您的数据目录 弹出面板中，从 选择目录 下拉列表中选择目录。如果该目录支持多种开放表格式，请在 开放表格式 中选择相应格式。
添加您的 catalog 连接
在下方选择您的 catalog，查看相关指南和前置条件。然后填写连接参数及数据库名称 —— 在 SQL 控制台中展示您的 catalog 表的 ClickHouse 数据库。
AWS Glue Catalog 可公开 Glue 数据目录中注册的 Iceberg 表。
连接前，请确认：
- ClickHouse 版本为 25.12+。
- Iceberg 表已在目标区域的 AWS Glue Data Catalog 中注册。
- 若使用访问密钥身份验证，你拥有一个 IAM 用户访问密钥，并且该密钥具有读取 Glue 元数据和底层 S3 对象的权限。
- 若使用 IAM 角色身份验证 (26.2+) ，你拥有一个信任 ClickHouse 服务角色的 IAM 角色。请在角色信任策略中包含 Settings → Network security 信息 中的服务角色 ARN。有关 IAM 策略示例，请参阅安全访问 Iceberg 数据。
在弹出面板中，输入 AWS 区域 (例如 us-west-2) ，然后选择一种身份验证方法：
访问密钥身份验证
- 选择 AWS Access Key 作为 身份验证方法。
- 输入 Access Key ID 和 Secret Access Key。
- 输入用于公开 Glue 表的 ClickHouse 数据库的 数据库名称。
IAM 角色身份验证 (26.2+)
- 选择 AWS IAM Role 作为 身份验证方法。
- 从弹出面板中复制 Service role ID (IAM)，并将其添加到 IAM 角色信任策略中。
- 输入 AWS Role ARN 和可选的 AWS Role Session Name。
- 输入用于公开 Glue 表的 ClickHouse 数据库的 数据库名称。
使用 Databricks 服务主体的 OAuth 客户端凭据，查询使用外部存储位置的 Unity Catalog Iceberg 表。有关完整设置，请参阅 Unity Catalog 指南。
连接前，请确认：
- ClickHouse 版本为 25.12 或更高版本。
- Unity Catalog 已配置外部数据访问。
- Databricks 服务主体具有 OAuth 客户端 ID 和密钥。该服务主体对要查询的表拥有
USE CATALOG、USE SCHEMA、USE EXTERNAL SCHEMA和SELECT特权。
在弹出面板中：
- 输入 Databricks Workspace URL (例如
dbc-1234567a-cbde.cloud.databricks.com) 。 - 输入要连接的 Databricks catalog 名称 (例如
icebench) 。 - 输入服务主体的 OAuth Client ID 和 Client secret。
- 输入 Database name，即用于公开 Unity Catalog 表的 ClickHouse 数据库名称。
使用 Databricks 个人访问令牌 (PAT) 查询使用外部存储位置的 Unity Catalog Delta Lake 表。有关完整配置，请参阅 Unity Catalog 指南。
连接前，请确认：
- ClickHouse 版本为 25.12 或更高版本。
- 已为 Unity Catalog 配置外部数据访问。
- Databricks 个人访问令牌 对目标表至少具有
EXTERNAL USE SCHEMA、USE CATALOG、USE SCHEMA和SELECT权限。
在弹出面板中：
- 输入 Databricks 工作区 URL (例如
dbc-1234567a-cbde.azuredatabricks.net) 。 - 输入要连接的 Databricks catalog 名称。
- 输入 个人访问令牌。
- 输入一个 数据库名称，用于创建可访问 Delta 表的 ClickHouse 数据库。
连接到任何实现 Iceberg REST Catalog 规范的 catalog。有关完整设置，请参阅 REST catalog 指南。
连接前，请确认：
- ClickHouse 版本为 25.12 或更高版本。
- 可从 ClickHouse Cloud 访问您的 REST catalog 端点。
- 根据 catalog 配置，您拥有 OAuth 客户端凭据或 Bearer 令牌。
- 您拥有用于表数据的 S3 或兼容 存储端点 URI (例如
s3://my-bucket/path) 。
在弹出面板中：
- 输入 Catalog URL (例如
https://catalog.example.com/v1) 。 - 输入 仓库或 catalog 命名空间 (例如
demo) 。 - 输入表存储的 存储端点 URI 前缀。
- 选择一种 身份验证方法：OAuth 客户端凭据或 Bearer 令牌，然后输入相应的凭据。
- 为用于公开 REST catalog 表的 ClickHouse 数据库输入 数据库名称。
使用 Azure AD 应用凭据查询 Microsoft Fabric OneLake 中的 Iceberg 表。完整设置步骤请参阅 Fabric OneLake 指南。
连接前，请确认：
- ClickHouse 版本为 25.12+。
- Fabric 工作区中已存在 Iceberg 表。
- 您拥有一个具有客户端 ID 和密钥的 Entra ID (Azure AD) 应用。
- 您已获取租户 ID、工作区 ID 和数据项 ID。请使用 Lakehouse 页面 URL 中的 Lakehouse ID。有关如何查找这些值，请参阅 Microsoft OneLake 前置条件。
在弹出面板中：
- 输入 Fabric 工作区 ID。
- 输入 数据项 ID — 请使用 Lakehouse ID。不支持仓库 ID。
- 输入 Entra ID 的 租户 ID、应用程序 (客户端) ID和客户端密钥。
- 为用于公开 OneLake 表的 ClickHouse 数据库输入数据库名称。
连接到 Snowflake Open Catalog (Polaris) 部署，以访问 Iceberg 表。有关完整设置，请参阅 Polaris 目录指南。
连接前，请确认：
- ClickHouse 版本为 26.2 或更高版本。
- 您拥有配置了 OAuth 客户端凭据的 Polaris 目录。
- 您拥有用于存储 Iceberg 表数据的端点 URI (例如
s3://company-iceberg-prod/warehouse/) 。
在弹出面板中：
- 输入目录账户标识符 (例如
ab12345.snowflakecomputing.com) 。 - 输入目录名称 (例如
snowflake_open_catalog) 。 - 输入 OAuth 客户端 ID和客户端密钥。
- 输入表存储的存储端点 URI 前缀。
- 输入用于公开您的 Polaris 表的 ClickHouse 数据库的数据库名称。
连接到 Google Cloud BigLake Metastore (即 Lakehouse 运行时目录) ，以访问 GCS 中的 Iceberg 表。完整设置步骤请参阅 BigLake Metastore 指南。
连接前，请确认：
- ClickHouse 版本为 26.2 或更高版本。
- 您已创建一个 BigLake Metastore 实例，其中包含存储在 GCS 中的 Iceberg 表。
- 您拥有包含客户端 ID、客户端密钥、刷新令牌和配额项目 ID 的 Google 应用默认凭据 (ADC)。
在弹出面板中：
- 输入 Google ADC 客户端 ID、客户端密钥、刷新令牌和 配额项目 ID。
- 输入存放表数据的 Cloud Storage 存储桶 URI (例如
gs://biglake-public-nyc-taxi-iceberg) 。 - 输入用于公开 BigLake 表的 ClickHouse 数据库的数据库名称。
保存连接
填写各字段后：
- 点击 添加目录。保存时，ClickHouse 会验证连接和凭据。
- 保存成功后，会显示确认提示，其中包含 在 SQL 控制台中查看 链接。您的目录会显示在 已链接目录 表中，其中包含连接状态和表数量。
在已链接目录行的 操作 菜单中，您可以删除目录连接。删除操作会从 ClickHouse 中移除该目录的数据库，但不会删除外部目录中的任何数据。
查询数据
查看目录中的表
在 数据源 页面中，找到 关联的目录 表中的目录，然后点击 查看表。
ClickHouse 将打开 SQL 控制台，选中您的目录数据库并列出可用表。
运行查询
在 SQL 编辑器中编写查询，然后点击 运行。请用反引号括住完整表名：
SELECT * FROM `identity_profiles.identity_profiles_iceberg`
故障排查
- 如果 SQL 控制台中未显示表：请检查凭据、网络访问权限以及目录中的表类型。确保您希望显示的表使用受支持的文件格式和表格式。
另请参阅
- 加速湖仓数据分析 — 将 catalog 中的表加载到 MergeTree，以支持重复查询
- 安全访问 Iceberg 数据 — 配置 IAM role 以访问 AWS Iceberg 和 Glue