创建 Catalog Connection

Catalog Connection 存储访问外部元数据服务（Hive Metastore、Databricks Unity Catalog、Iceberg REST Catalog 等）所需的认证信息，供 External Catalog 和 External Schema 使用。

支持的类型

HMS

databricks

ICEBERG_REST

HMS（Hive Metastore）

语法

CREATE CATALOG CONNECTION [IF NOT EXISTS] <connection_name> TYPE HMS HIVE_METASTORE_URIS = '<thrift://host:port>' STORAGE_CONNECTION = '<storage_connection_name>' [AUTH_TYPE = 'kerberos' KERBEROS_CLIENT_PRINCIPAL = '<principal>' KERBEROS_SERVICE_PRINCIPAL = '<principal>' KERBEROS_KRB5_CONFIG_PATH = '<volume_path>' KERBEROS_KEYTAB_PATH = '<volume_path>'];

参数说明

• HIVE_METASTORE_URIS

  HIVE_METASTORE_URIS
  ：Hive Metastore 服务地址，格式为

  thrift://host:9083

  thrift://host:9083
  ，端口通常是 9083

• STORAGE_CONNECTION

  STORAGE_CONNECTION
  ：已创建的存储连接名称，用于读取 Hive 数据文件（OSS/COS/S3/HDFS）

• AUTH_TYPE

  AUTH_TYPE
  ：认证类型，不填默认无认证；填

  'kerberos'

  'kerberos'
  启用 Kerberos 认证
• Kerberos 参数仅在

  AUTH_TYPE = 'kerberos'

  AUTH_TYPE = 'kerberos'
  时需要：配置文件和 keytab 文件须提前通过

  PUT

  PUT
  命令上传至 User Volume

示例

Hive ON OSS（阿里云）

-- 步骤 1：创建存储连接 CREATE STORAGE CONNECTION IF NOT EXISTS oss_conn TYPE OSS ACCESS_ID = 'LTAIxxxxxxxxxxxx' ACCESS_KEY = 'T8Gexxxxxxmtxxxxxx' ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com'; -- 步骤 2：创建 Catalog Connection -- 确保 HMS 所在服务器与 Lakehouse 网络已打通，参考：创建阿里云终端节点服务 CREATE CATALOG CONNECTION IF NOT EXISTS hive_oss_conn TYPE HMS HIVE_METASTORE_URIS = 'thrift://192.168.1.100:9083' STORAGE_CONNECTION = 'oss_conn';

Hive ON COS（腾讯云）

CREATE STORAGE CONNECTION IF NOT EXISTS cos_conn TYPE COS ACCESS_KEY = '<access_key>' SECRET_KEY = '<secret_key>' REGION = 'ap-shanghai' APP_ID = '1310000503'; CREATE CATALOG CONNECTION IF NOT EXISTS hive_cos_conn TYPE HMS HIVE_METASTORE_URIS = 'thrift://192.168.1.100:9083' STORAGE_CONNECTION = 'cos_conn';

Hive ON S3（AWS）

CREATE STORAGE CONNECTION IF NOT EXISTS s3_conn TYPE S3 ACCESS_KEY = 'AKIAQNBSBP6EIJE33***' SECRET_KEY = '7kfheDrmq***' ENDPOINT = 's3.cn-north-1.amazonaws.com.cn' REGION = 'cn-north-1'; CREATE CATALOG CONNECTION IF NOT EXISTS hive_s3_conn TYPE HMS HIVE_METASTORE_URIS = 'thrift://192.168.1.100:9083' STORAGE_CONNECTION = 's3_conn';

Hive + Kerberos 认证

-- 先上传认证文件到 User Volume PUT '/etc/krb5.conf' TO USER VOLUME FILE 'krb5.conf'; PUT '/path/to/hive.keytab' TO USER VOLUME FILE 'hive.keytab'; CREATE CATALOG CONNECTION IF NOT EXISTS hive_kerberos_conn TYPE HMS HIVE_METASTORE_URIS = 'thrift://your-hms-host:9083' STORAGE_CONNECTION = 'oss_conn' AUTH_TYPE = 'kerberos' KERBEROS_CLIENT_PRINCIPAL = 'hive/localhost@YOUR-REALM.COM' KERBEROS_SERVICE_PRINCIPAL = 'hive/localhost@YOUR-REALM.COM' KERBEROS_KRB5_CONFIG_PATH = 'volume:user//~/krb5.conf' KERBEROS_KEYTAB_PATH = 'volume:user//~/hive.keytab';

Databricks Unity Catalog

语法

CREATE CATALOG CONNECTION [IF NOT EXISTS] <connection_name> TYPE databricks HOST = '<https://workspace-url>' CLIENT_ID = '<oauth_client_id>' CLIENT_SECRET = '<oauth_client_secret>' ACCESS_REGION = '<region>';

参数说明

• HOST

  HOST
  ：Databricks 工作区 URL，格式为

  https://dbc-xxxxx.cloud.databricks.com

  https://dbc-xxxxx.cloud.databricks.com

• CLIENT_ID / CLIENT_SECRET

  CLIENT_ID / CLIENT_SECRET
  ：OAuth M2M 认证凭据，在 Databricks 控制台创建 Service Principal 后获取，参考 Databricks OAuth M2M 文档

• ACCESS_REGION

  ACCESS_REGION
  ：Databricks 工作区所在区域，如

  us-west-2

  us-west-2

Databricks 侧前置配置

1. 创建 Service Principal，获取

   CLIENT_ID

   CLIENT_ID
   和

   CLIENT_SECRET

   CLIENT_SECRET
2. 在 Metastore 开启 External Data Access
3. 向 Service Principal 授权：

   GRANT EXTERNAL USE SCHEMA ON SCHEMA <catalog>.<schema> TO `<service_principal_id>`;

示例

CREATE CATALOG CONNECTION IF NOT EXISTS my_databricks_conn TYPE databricks HOST = 'https://dbc-12345678-9abc.cloud.databricks.com' CLIENT_ID = '12345678-9abc-def0-1234-56789abcdef0' CLIENT_SECRET = 'abcdef1234567890abcdef1234567890' ACCESS_REGION = 'us-west-2';

验证连接：

CREATE EXTERNAL CATALOG my_databricks_catalog CONNECTION my_databricks_conn OPTIONS ('catalog' = 'main'); SHOW SCHEMAS IN my_databricks_catalog;

Iceberg REST Catalog

Iceberg REST 协议是一个开放标准，任何兼容该协议的服务（自建 Iceberg REST 服务、Polaris、Dremio、Snowflake Open Catalog 等）均使用相同的

TYPE ICEBERG_REST

语法

CREATE CATALOG CONNECTION [IF NOT EXISTS] <connection_name> TYPE ICEBERG_REST URI = '<catalog_endpoint>' [ACCESS_REGION = '<region>'] [OAUTH_CLIENT_ID = '<client_id>' OAUTH_CLIENT_SECRET = '<client_secret>' OAUTH_SCOPE = '<scope>' NAMESPACE = '<namespace>' WAREHOUSE = '<warehouse>'] [WITH PROPERTIES ('<key>' = '<value>', ...)];

参数说明

• URI

  URI
  ：Iceberg REST Catalog 的 API 端点（必填）

• ACCESS_REGION

  ACCESS_REGION
  ：底层数据文件所在的云存储区域

• OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET

  OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET
  ：OAuth 认证凭据，Snowflake Open Catalog 等需要 OAuth 的服务必填

• OAUTH_SCOPE

  OAUTH_SCOPE
  ：OAuth 授权范围，Snowflake Open Catalog 固定为

  'PRINCIPAL_ROLE:ALL'

  'PRINCIPAL_ROLE:ALL'

• NAMESPACE

  NAMESPACE
  ：Iceberg 命名空间（数据库名），部分服务需要

• WAREHOUSE

  WAREHOUSE
  ：Catalog 名称，部分服务（如 Snowflake Open Catalog）需要

• WITH PROPERTIES

  WITH PROPERTIES
  ：额外的底层配置，如

  'io-impl'

  'io-impl'
  （指定文件 IO 实现）

TYPE

=

TYPE = ICEBERG_REST

示例：通用 Iceberg REST Catalog（无认证）

CREATE CATALOG CONNECTION IF NOT EXISTS iceberg_conn TYPE ICEBERG_REST URI = 'https://your-iceberg-rest-catalog/api/catalog' ACCESS_REGION = 'cn-hangzhou'; -- 创建 External Catalog（不需要 OPTIONS） CREATE EXTERNAL CATALOG iceberg_catalog CONNECTION iceberg_conn;

示例：Snowflake Open Catalog（OAuth）

Snowflake Open Catalog 是基于 Iceberg REST 协议的托管服务，需要额外的 OAuth 参数。

CREATE CATALOG CONNECTION IF NOT EXISTS snow_opencatalog_conn TYPE ICEBERG_REST URI = 'https://<account>.snowflakecomputing.com/polaris/api/catalog' ACCESS_REGION = 'ap-southeast-1' OAUTH_CLIENT_ID = '<client_id>' OAUTH_CLIENT_SECRET = '<client_secret>' OAUTH_SCOPE = 'PRINCIPAL_ROLE:ALL' NAMESPACE = '<your_database>' WAREHOUSE = '<your_catalog>' WITH PROPERTIES ( 'client.region' = 'ap-southeast-1', 'io-impl' = 'org.apache.iceberg.aws.s3.S3FileIO' ); -- 创建 External Catalog（不需要 OPTIONS，连接本身已含命名空间信息） CREATE EXTERNAL CATALOG snow_catalog CONNECTION snow_opencatalog_conn;

详细配置步骤参考：访问 Snowflake Open Catalog 的 Iceberg 表

管理 Catalog Connection

-- 查看所有连接 SHOW CONNECTIONS; -- 查看连接详情 DESC CONNECTION my_conn; -- 删除连接（删除前需先删除依赖该连接的 External Catalog） DROP CONNECTION my_conn;

相关文档

• 创建 External Catalog — 基于 Catalog Connection 创建 External Catalog
• 创建 External Schema — 将外部数据库挂载到当前工作空间
• 创建存储连接 — HMS 需要配套的 Storage Connection
• 访问 Snowflake Open Catalog 的 Iceberg 表
• Databricks Unity Catalog 联邦查询实践 — Databricks 侧配置到查询验证的完整操作路径