> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Unity Catalog
> 本指南将逐步介绍如何使用 ClickHouse 和 Unity Catalog 查询存储在 S3 存储桶中的数据。
export const galaxyOnClick = eventName => () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return
Beta
;
}
return ;
};
ClickHouse 支持与多个目录 (如 Unity、Glue、Polaris 等) 集成。本指南将逐步说明如何使用 ClickHouse 和 [Unity Catalog](https://www.databricks.com/product/unity-catalog) 查询由 Databricks 管理的数据。
Databricks 的湖仓支持多种数据格式。借助 ClickHouse，您可以以 Delta 和 Iceberg 两种方式查询 Unity Catalog 表。
由于此功能仍处于 Experimental 阶段，您需要使用以下命令启用它：
`SET allow_experimental_database_unity_catalog = 1;`
## 在 Databricks 中配置 Unity
要让 ClickHouse 与 Unity Catalog 交互，您需要确保 Unity Catalog 已配置为允许外部读取方访问。为此，可按照[“启用对 Unity Catalog 的外部数据访问”](https://docs.databricks.com/aws/en/external-access/admin)指南进行配置。
完成目录 配置后，您必须为 ClickHouse 生成凭据。根据您与 Unity 的交互方式不同，可以使用以下两种方法：
* 对于 Iceberg 客户端，使用 [service principal](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) 进行身份验证。
* 对于 Delta 客户端，使用个人访问令牌 ([PAT](https://docs.databricks.com/aws/en/dev-tools/auth/pat)) 。
### 所需的 PAT 令牌权限
使用 PAT 进行读访问时，该令牌必须具备允许 ClickHouse 列出并读取 Unity Catalog 元数据的权限。请确保该 PAT 至少具有 `EXTERNAL USE SCHEMA` [权限](https://docs.databricks.com/aws/en/external-access/admin#grant-a-principal-unity-catalog-privileges)，以及该表上的 `SELECT` 权限、其父 目录 上的 `USE CATALOG` 权限和其父 schema 上的 `USE SCHEMA` 权限。
## 创建 Unity Catalog 与 ClickHouse 之间的连接
在完成 Unity Catalog 配置并启用身份验证后，建立 ClickHouse 与 Unity Catalog 之间的连接。
### 读取 Delta
```sql theme={null}
CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS warehouse = 'CATALOG_NAME', catalog_credential = '', catalog_type = 'unity'
```
### 读取 Iceberg 表
要访问托管的 Iceberg 表：
```sql theme={null}
CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://.cloud.databricks.com/api/2.1/unity-catalog/iceberg-rest')
SETTINGS catalog_type = 'rest', catalog_credential = ':', warehouse = 'workspace',
oauth_server_uri = 'https://.cloud.databricks.com/oidc/v1/token', auth_scope = 'all-apis,sql'
```
## 使用 ClickHouse 查询 Unity Catalog 中的表
完成连接配置后，你就可以开始通过 Unity Catalog 进行查询了。例如：
```sql theme={null}
USE unity;
SHOW TABLES;
```
```response theme={null}
┌─name───────────────────────────────────────────────┐
│ clickbench.delta_hits │
│ demo.fake_user │
│ information_schema.catalog_privileges │
│ information_schema.catalog_tags │
│ information_schema.catalogs │
│ information_schema.check_constraints │
│ information_schema.column_masks │
│ information_schema.column_tags │
│ information_schema.columns │
│ information_schema.constraint_column_usage │
│ information_schema.constraint_table_usage │
│ information_schema.information_schema_catalog_name │
│ information_schema.key_column_usage │
│ information_schema.parameters │
│ information_schema.referential_constraints │
│ information_schema.routine_columns │
│ information_schema.routine_privileges │
│ information_schema.routines │
│ information_schema.row_filters │
│ information_schema.schema_privileges │
│ information_schema.schema_tags │
│ information_schema.schemata │
│ information_schema.table_constraints │
│ information_schema.table_privileges │
│ information_schema.table_tags │
│ information_schema.tables │
│ information_schema.views │
│ information_schema.volume_privileges │
│ information_schema.volume_tags │
│ information_schema.volumes │
│ uniform.delta_hits │
└────────────────────────────────────────────────────┘
```
```sql theme={null}
SHOW TABLES
```
```response theme={null}
┌─name───────────────┐
│ uniform.delta_hits │
└────────────────────┘
```
要查询某个表：
```sql theme={null}
SELECT count(*) FROM `uniform.delta_hits`
```
**必须使用反引号**
必须使用反引号，因为 ClickHouse 仅支持一个命名空间。
要查看该表的 DDL：
```sql theme={null}
SHOW CREATE TABLE `uniform.delta_hits`
CREATE TABLE unity_uniform.`uniform.delta_hits`
(
`WatchID` Int64,
`JavaEnable` Int32,
`Title` String,
`GoodEvent` Int32,
`EventTime` DateTime64(6, 'UTC'),
`EventDate` Date,
`CounterID` Int32,
`ClientIP` Int32,
...
`FromTag` String,
`HasGCLID` Int32,
`RefererHash` Int64,
`URLHash` Int64,
`CLID` Int32
)
ENGINE = Iceberg('s3://);
```
## 将数据从数据湖导入 ClickHouse
如果需要将 Databricks 中的数据导入 ClickHouse，请先创建一个本地 ClickHouse 表：
```sql theme={null}
CREATE TABLE hits
(
`WatchID` Int64,
`JavaEnable` Int32,
`Title` String,
`GoodEvent` Int32,
`EventTime` DateTime64(6, 'UTC'),
`EventDate` Date,
`CounterID` Int32,
`ClientIP` Int32,
...
`FromTag` String,
`HasGCLID` Int32,
`RefererHash` Int64,
`URLHash` Int64,
`CLID` Int32
)
PRIMARY KEY (CounterID, EventDate, UserID, EventTime, WatchID);
```
然后通过 `INSERT INTO SELECT` 从您的 Unity Catalog 表中加载数据：
```sql theme={null}
INSERT INTO hits SELECT * FROM unity_uniform.`uniform.delta_hits`;
```