--- title: "通过 Catalog 加载 Hive 表 - OceanBase 数据库 V4.4.2 | OceanBase 文档中心" description: 通过 Catalog 加载 Hive 表 OceanBase 自 V4.4.1 版本起支持通过 HMS（Hive Metastore）连接，创建 HMS Catalog，从而统一访问由 Hive Metastore 管理的表——包括传统的 Hive 表以及以 Iceberg 格式存储、但元数据注册在 Hive Met… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.4.2 LTS # 通过 Catalog 加载 Hive 表 更新时间：2026-06-24 20:11:47 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.4.2/zh-CN/620.obap/400.data-lake/200.data-lake-integration/100.hive/100.load-hive-via-catalog.md) OceanBase 自 V4.4.1 版本起支持通过 HMS（Hive Metastore）连接，创建 HMS Catalog，从而统一访问由 Hive Metastore 管理的表——包括传统的 Hive 表以及以 Iceberg 格式存储、但元数据注册在 Hive Metastore 中的表。 #### 注意 HMS Catalog 的 `CREATE EXTERNAL CATALOG ... TYPE = 'HMS'` 语法见本文；完整 SQL 参考以 [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005286499) 当前版本是否已收录为准。需 **V4.4.1 及以上**、**MySQL 模式**。 - 统一元数据管理：通过 Hive Metastore 自动同步表结构。 - 联邦查询：与 OceanBase 内部表 JOIN 分析。 - 只读安全：防止误操作修改源数据。 OceanBase 从 V4.4.1 版本开始正式支持 HMS Catalog 功能。本文档为便于用户提前了解和规划 OceanBase 数据库的 AP 能力，已在 V4.3.5 文档集中提供相关使用说明。 ## 支持能力 - **只读访问**：所有 HMS Catalog 下的对象均为只读，当前暂不支持执行 `INSERT`、`UPDATE`、`DROP TABLE` 等 DML/DDL 操作。 - **支持表类型**：Hive 表，即 HMS Catalog 的原生表类型。 - **Hive 版本兼容性** - 支持版本：Hive 1.2.x、Hive 2.3.x、Hive 3.1.x、Hive 4.x。 - **HMS Catalog 名称**：Hive Metastore 3.x 开始支持在 HMS 内维护多个 Catalog，用于资源管理。连接此类 HMS 时，可通过 `HMS_CATALOG_NAME` 指定要访问的 Catalog。未指定该参数时，表示不显式指定 Catalog，由 HMS 按默认行为处理；在 Hive Metastore 3.x 及以上版本中，默认 Catalog 名称通常为 hive。 - **关于 Iceberg 表的兼容性说明**： - Hive 4.x 及以上：Hive 引擎原生支持 Iceberg 表，可通过 Hive 自身完成表创建、元数据更新等操作，OceanBase 可直接通过 HMS Catalog 访问。 - Hive 1.2.x / 2.3.x / 3.1.x：Hive 本身不支持 Iceberg。此类环境中，Iceberg 表通常由 Spark、Flink 等计算引擎创建并写入，同时将 Iceberg 元数据注册到 Hive Metastore 中。OceanBase 依赖 HMS 中的这些元数据信息来识别和读取 Iceberg 表。 ## 使用前提 1. **权限要求** - 当前用户需具备 `CREATE CATALOG`、`USE CATALOG` 等 Catalog 相关权限（**MySQL 模式**）。Catalog 能力当前仅 MySQL 模式支持。 2. **环境依赖**：若底层存储为 HDFS，需提前部署 Java SDK 环境 参见 [部署 OceanBase 数据库 JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005282362)。 3. **外部访问** - **HMS 服务**：OceanBase 集群需能访问 Hive Metastore（Thrift 协议）。HMS 服务的地址和端口应由客户运维团队提供；开源 Hive 默认使用端口 9083，但实际部署中可能有所不同，请以现场配置为准。 - **存储系统**：所有 OBServer 节点对 HDFS/S3/OSS 具备读权限。若路径权限受限或启用 Kerberos，需通过 Location 配置相应认证凭据，参见下文 **HMS Catalog 与 HDFS 存储的认证机制**章节。 ## 创建 HMS Catalog 语法 ```sql CREATE EXTERNAL CATALOG [IF NOT EXISTS] catalog_name PROPERTIES ( TYPE = 'HMS', URI = 'thrift://host:port', [PRINCIPAL = '...'], [KEYTAB = '...'], [KRB5CONF = '...'], [MAX_CLIENT_POOL_SIZE = 20], [SOCKET_TIMEOUT = 10000000], [HMS_CATALOG_NAME = '...'] ); ``` ## 参数说明 | 参数 | 是否必填 | 参数说明 | | --- | --- | --- | | TYPE | 必填 | 固定为 `'HMS'` | | URI | 必填 | HMS Thrift 地址，格式：`thrift://$host:$port` - `$host`：表示 thrift IP 地址。 - `$port`：表示 thrift 端口。HMS 服务的地址和端口应由客户运维团队提供；开源 Hive 默认使用端口 9083，但实际部署中可能有所不同，请以现场配置为准。 如果您的 HMS 开启了高可用模式，此处可以填写多个 HMS 地址并用逗号分隔，例如：`"thrift://:,thrift://:,thrift://:"`。 | | PRINCIPAL | 可选 | Kerberos 主体（通常以 `service/HOST@REGION.com` 形式存在，例如 `hive/hadoop@QA.COM`。） | | KEYTAB | 可选 | 指定访问启用 Kerberos 认证的 HMS 服务时，所需的 KEYTAB 密钥文件路径。如果 OceanBase 集群为分布式部署，那么相关的 OBServer 对应机器所有节点，相关路径都需要存在该文件。**注意**：仅在 HMS 启用 Kerberos 认证时，需要设置参数 KEYTAB。 | | KRB5CONF | 可选 | Kerberos 配置文件路径（如 `/etc/krb5.conf`）。如果 OceanBase 集群为分布式部署，那么相关的 OBServer 对应机器所有节点，相关路径都需要存在该文件。 | | MAX_CLIENT_POOL_SIZE | 可选 | HMS 客户端连接池大小（默认 20，表示当前的 HMS Catalog 最多可启动 20 个对接 HMS 服务的客户端。） | | SOCKET_TIMEOUT | 可选 | 连接 Hive metastore 超时超时（微秒，默认为 10000000（10s）） | | HMS_CATALOG_NAME | 可选 | Hive Metastore 3.x 开始支持在 HMS 内维护多个 Catalog，用于资源管理。连接此类 HMS 时，可通过 `HMS_CATALOG_NAME` 指定要访问的 Catalog。未指定该参数时，表示不显式指定 Catalog，由 HMS 按默认行为处理；在 Hive Metastore 3.x 及以上版本中，默认 Catalog 名称通常为 hive。 | ## 创建 SIMPLE 认证的 HMS Catalog 普通认证模式，不需要设置 Location 认证。 ```sql obclient> CREATE EXTERNAL CATALOG test_hms_catalog PROPERTIES = ( TYPE = 'HMS', URI = "thrift://xxx.xxx.xxx.xxx:xxxx", HMS_CATALOG_NAME = 'hive' ); ``` #### 说明 若 HMS 版本为 3.1.3 及以上，且表注册在非默认 Catalog 中，需通过 `HMS_CATALOG_NAME` 指定目标 Catalog 名称。访问默认 Catalog 时，可设置为 `hive`，也可省略该参数（默认为空，由 HMS 侧默认行为决定）。 更多关于 Hadoop 认证模式的信息，参见下文中的**HMS Catalog 与 HDFS 存储的认证机制**章节。 ## 创建 Kerberos 认证的 HMS Catalog 更多关于 Hadoop 认证模式的信息，参见下文中的**HMS Catalog 与 HDFS 存储的认证机制**章节。 ### 步骤 1：创建 Kerberos 认证的 HMS Catalog（元数据层） ```sql CREATE EXTERNAL CATALOG hms_kerberos PROPERTIES ( TYPE = 'HMS', URI = 'thrift://hms.example.com:9083', PRINCIPAL = 'hive/hms.example.com@EXAMPLE.COM', KEYTAB = '/etc/ob/hive.keytab', KRB5CONF = '/etc/krb5.conf', HMS_CATALOG_NAME = 'hive' ); ``` ### 步骤 2：创建 Kerberos 认证的 HDFS Location（数据层） ```sql CREATE LOCATION hdfs_kerberos_ha URL = 'hdfs://namenode:8020/' CREDENTIAL ( PRINCIPAL = "ob_hdfs@EXAMPLE.COM", KEYTAB = "/etc/ob/hdfs.keytab", KRB5CONF = "/etc/krb5.conf", CONFIGS = '...' -- 如上 HA 配置 ); ``` HMS Catalog 可正常发现表结构，Location 可安全读取 HDFS 数据文件。 ## 切换 Catalog ```sql SET CATALOG hms_catalog; ``` ## 通过 Catalog 查询外部数据源 ```sql -- Hive 表 SELECT city, COUNT(*) FROM hive_db.customer WHERE dt >= '2025-04-01' GROUP BY city; -- Iceberg 表 SELECT product_id, SUM(sales) FROM iceberg_db.sales_iceberg WHERE event_time >= '2025-04-01' GROUP BY product_id; -- 联邦查询 SELECT o.order_id, h.city FROM internal.test_db.orders o JOIN hms_catalog.hive_db.customer h ON o.user_id = h.id; ``` ## HMS Catalog 与 HDFS 存储的认证机制 在 OceanBase 中，访问 Hive Metastore（HMS）涉及两层独立的认证： - **Catalog 层**：用于连接 Hive Metastore（获取表结构、分区等元数据）。 - **Location 层**：用于读取实际存储在 HDFS 等文件系统中的数据文件。 这两层的认证方式需分别配置，并必须与 Hadoop 集群的安全策略保持一致。 ### Hadoop 认证模式由服务端决定 Hadoop 集群通过 `hdfs-site.xml` 中的配置项 `hadoop.security.authentication` 定义其安全模式： ```xml hadoop.security.authentication kerberos ``` - `kerberos`：启用 Kerberos 认证，所有客户端（包括 HMS Client 和 HDFS Client）必须通过 Kerberos 身份验证。 - `simple`：Hadoop 服务端信任客户端声明的操作系统用户名，不进行密码或凭证验证；权限控制仅基于 HDFS 文件/目录的属主、属组及 POSIX 权限位（如 `drwxr-xr-x（755）` ），无 Kerberos 身份认证。 #### 注意 该配置位于 Hadoop 服务端（`$HADOOP_HOME/etc/hadoop/hdfs-site.xml`），OceanBase 不直接读取此文件，而是通过自身的 Catalog 和 Location 配置来适配该模式。 ### OceanBase 的认证配置方式 | Hadoop 模式 | HMS Catalog 配置 | HDFS Location 配置 | | --- | --- | --- | | SIMPLE | 创建 Catalog 时不指定认证方式（默认 SIMPLE） | - 若 HDFS 目录对所有用户可读（如权限 `drwxr-xr-x`），无需创建 Location - 若目录仅限特定用户访问（如属主为 hive、impala），需通过 `CREATE LOCATION ... CREDENTIAL (USERNAME = 'xxx')` 显式指定有权限的 HDFS 用户。 | | KERBEROS | 创建 Catalog 时指定 `AUTHENTICATION = 'KERBEROS'`，并提供 `PRINCIPAL`、`KEYTAB`、`KRB5CONF`。 | 必须创建 Kerberos 认证的 HDFS Location，同样提供 Principal、Keytab 和 krb5.conf | **重要配置规则**：若 HMS 或 HDFS 任一启用了 Kerberos，请检查部署是否正确。 ### 两种认证模式详解 #### SIMPLE 模式（开发/测试环境常见） **适用场景：** - HDFS 未启用 Kerberos，仅依赖 Linux 文件权限控制。 - 表由特定用户写入（如 Impala 写入 HDFS 路径属主为 impala；Hive on Tez 属主为作业提交用户如 hive）。 **配置要求：** - **匿名可读路径**：● HDFS 目录权限开放（如 drwxr-xr-x (755)），任意用户可读 无需创建 Location。 - 含义：属主（owner）有读、写、执行权限（rwx = 4+2+1 = 7）； 所属组（group）和其他用户（others）仅有读和执行权限（r-x = 4+0+1 = 5）； - 此类路径下，OceanBase 无需创建 Location，可直接访问。 - **受限路径**：若 OceanBase Observer 进程用户（如 admin）不在目录授权用户/组中，则必须： 若 OceanBase Observer 进程用户（如 admin）不属于 HDFS 路径权限允许访问的用户或用户组，则需要创建 Location，并指定一个在 HDFS 侧具有相应访问权限的用户。 ```sql CREATE LOCATION my_loc URL = 'hdfs://mycluster/' CREDENTIAL (USERNAME = 'username'); ``` ##### 场景 1：无需 Kerberos，且无需指定 HDFS 用户（默认匿名） - 适用：适用于 HDFS 集群 未启用 kerberos 认证（即hadoop.security.authentication=simple ） 的开发或测试环境。 - 操作：Location 无需创建。 ##### 场景 2：无需 Kerberos，但需指定 HDFS 用户 - **适用**：适用于 HDFS 集群 未启用 kerberos 认证（即 `hadoop.security.authentication=simple`） 的开发或测试环境，但目标 Hive 表的数据文件存储在 权限受限的 HDFS 路径 上（例如由 Impala、Hive 或其他引擎写入，路径属主为特定用户，且未开放全局读权限）。 - **典型情况**： - 表由 Impala 写入 HDFS 路径属主为 impala。 - 表由 Hive 作业提交用户写入 → 属主可能是 hive、etl_user 等。 - OceanBase Observer 默认以操作系统用户（如 admin）访问 HDFS，若该用户无读权限，则查询失败。 - **示例**：假设某 Hive 表由 Impala 写入，其 HDFS 路径为 `hdfs://namenode:8020/warehouse/sales.db/click_log` ```sql CREATE LOCATION hdfs_impala_data URL = 'hdfs://namenode:8020/' -- URL，见下方说明 CREDENTIAL ( USERNAME = 'username' ); ``` **如何确定正确的 URL:** 1. 在 Hive CLI 或 Beeline 中执行： ```sql SHOW CREATE TABLE your_db.your_table; ``` 2. 查看输出中的 LOCATION 字段，例如： ```sql LOCATION 'hdfs://namenode:8020/warehouse/your_db.db/your_table' ``` 3. 提取 协议 + 服务名/主机名 + 服务端口 作为 URL，也就是说，CREATE LOCATION 中的 URL 填 `hdfs://namenode:8020/`。 ##### 场景 3：未启用 Kerberos，且 HDFS 为高可用（HA） **操作**：无需设置 PRINCIPAL、KEYTAB 和 KRB5CONF 参数。 ```sql CREATE LOCATION hdfs_location_ha URL = 'hdfs://${nameservice_id}' -- 推荐使用逻辑服务名 CREDENTIAL ( CONFIGS = 'dfs.nameservices=${nameservice id}#dfs.ha.namenodes.${nameservice id}=${namenode1}, ${namenode2}#dfs.namenode.rpc-address.${nameservice id}.${namenode1}=${namenode 1 address}#dfs.namenode.rpc-address.${nameservice id}.${namenode2}=${namenode 2 address}#dfs.ha.automatic-failover.enabled.${nameservice id}=true#dfs.client.failover.proxy.provider.${nameservice id}=org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider' ); ``` #### KERBEROS 模式（生产环境标准） **适用场景：** - 企业级 Hadoop 集群，HMS 或 HDFS 启用 Kerberos 安全认证。 **配置要求：** - **HMS Catalog**：在 `CREATE EXTERNAL CATALOG` 的 `PROPERTIES` 中指定 `PRINCIPAL`、`KEYTAB`、`KRB5CONF`。 - **HDFS Location**：参见上文 **步骤 2：创建 Kerberos 认证的 HDFS Location** 及下文场景 4、场景 5；`CREATE LOCATION` 语法以 SQL 参考为准。 ##### 场景 4：启用 Kerberos，且 HDFS 为单 NameNode（非 HA 模式） ```sql -- 创建 LOCATION：Kerberos 认证 + 单点 HDFS CREATE LOCATION hdfs_kerberos_single URL = 'hdfs://namenode.example.com:8020/' -- 请通过 SHOW CREATE TABLE 获取表的完整 HDFS 路径，提取根 URL CREDENTIAL ( PRINCIPAL = "hdfs/TEST@EXAMPLE.COM", KEYTAB = "/data/hdfs.keytab", KRB5CONF = "/data/krb5.conf", CONFIGS = 'dfs.data.transfer.protection=integrity' ); ``` #### 说明 - `CONFIGS` 中的 `dfs.data.transfer.protection` 参数用于指定 HDFS 数据传输通道的安全级别（如 `authentication`、`integrity`、`privacy` 或 `null`）。 - 该值必须与 Hadoop 集群 `hdfs-site.xml` 中配置的 `dfs.data.transfer.protection` 完全一致，否则在读取数据时可能因安全策略不匹配而失败。 - 建议从 Hadoop 管理员处确认该配置项的实际值，或直接查看 HDFS 集群的 `hdfs-site.xml` 文件。 ##### 场景 5：启用 Kerberos，且 HDFS 为高可用（HA） ```sql CREATE LOCATION hdfs_kerberos_ha URL = 'hdfs://${nameservice id}' -- 推荐使用逻辑服务名 CREDENTIAL ( PRINCIPAL = "ob_hdfs@EXAMPLE.COM", KEYTAB = "/etc/ob/hdfs.keytab", KRB5CONF = "/etc/krb5.conf", CONFIGS = 'dfs.data.transfer.protection=integrity#dfs.nameservices=mycluster#dfs.ha.namenodes.mycluster=nn1,nn2#dfs.namenode.rpc-address.mycluster.nn1=nn1:8020#dfs.namenode.rpc-address.mycluster.nn2=nn2:8020#dfs.client.failover.proxy.provider.mycluster=org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider' ); ``` #### 说明 - 所有 OBServer 节点需部署相同的 keytab 和 krb5.conf。 - 若遇 “Unknown Host” 错误，请在 /etc/hosts 添加 HDFS 节点映射。 更多关于 Location 参数配置，请参见 [CREATE EXTERNAL TABLE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005286424) 中的 `LOCATION` 章节及 [Catalog 与外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006325512)。 ## 配置说明与注意事项 - **认证分离**：Catalog（元数据）与 Location（数据）认证独立配置。 - **模式对齐**：OceanBase 的认证方式必须与 Hadoop 集群的 `hadoop.security.authentication` 设置一致。 - **Kerberos 强制一致**：只要 HMS 或 HDFS 启用 Kerberos，两者都必须配置 Kerberos 凭据。 - **SIMPLE 模式需关注权限**：确保 Observer 用户或指定 USER 对 HDFS 路径有读权限。 - **HMS Catalog 名称**：HMS 3.1.3 及以上版本若存在多个 Catalog，创建 HMS Catalog 时需确认 `HMS_CATALOG_NAME` 与 HMS 侧实际 Catalog 名称一致。 ## 相关文档 - [Catalog 与外部表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006325512) - [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006325513) - [Hive 表（HMS）](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006325511) - [Catalog 概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005283593) - [部署 OceanBase 数据库 JAVA SDK 环境](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005282362) - [CREATE EXTERNAL CATALOG](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005286499) 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线