通过 Catalog 加载 Hive 表

OceanBase 自 V4.4.1 版本起支持通过 HMS（Hive Metastore）连接，创建 HMS Catalog，从而统一访问由 Hive Metastore 管理的表——包括传统的 Hive 表以及以 Iceberg 格式存储、但元数据注册在 Hive Metastore 中的表。

• 统一元数据管理：通过 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 环境。

3. 外部访问

   • HMS 服务：OceanBase 集群需能访问 Hive Metastore（Thrift 协议）。HMS 服务的地址和端口应由客户运维团队提供；开源 Hive 默认使用端口 9083，但实际部署中可能有所不同，请以现场配置为准。
   • 存储系统：所有 OBServer 节点对 HDFS/S3/OSS 具备读权限。若路径权限受限或启用 Kerberos，需通过 Location 配置相应认证凭据，参见下文 HMS Catalog 与 HDFS 存储的认证机制章节。

创建 HMS Catalog 语法

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 = '...']
);

参数说明

创建 SIMPLE 认证的 HMS Catalog

普通认证模式，不需要设置 Location 认证。

obclient> CREATE EXTERNAL CATALOG test_hms_catalog
    PROPERTIES = (
        TYPE = 'HMS',
        URI = "thrift://xxx.xxx.xxx.xxx:xxxx",
        HMS_CATALOG_NAME = 'hive'
    );

更多关于 Hadoop 认证模式的信息，参见下文中的HMS Catalog 与 HDFS 存储的认证机制章节。

创建 Kerberos 认证的 HMS Catalog

更多关于 Hadoop 认证模式的信息，参见下文中的HMS Catalog 与 HDFS 存储的认证机制章节。

步骤 1：创建 Kerberos 认证的 HMS Catalog（元数据层）

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（数据层）

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

SET CATALOG hms_catalog;

通过 Catalog 查询外部数据源

-- 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 定义其安全模式：

<property>
  <name>hadoop.security.authentication</name>
  <value>kerberos</value> <!-- 或 simple -->
</property>

• kerberos：启用 Kerberos 认证，所有客户端（包括 HMS Client 和 HDFS Client）必须通过 Kerberos 身份验证。
• simple：Hadoop 服务端信任客户端声明的操作系统用户名，不进行密码或凭证验证；权限控制仅基于 HDFS 文件/目录的属主、属组及 POSIX 权限位（如 drwxr-xr-x（755） ），无 Kerberos 身份认证。

OceanBase 的认证配置方式

重要配置规则：若 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 侧具有相应访问权限的用户。

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

CREATE LOCATION hdfs_impala_data
URL = 'hdfs://namenode:8020/'    -- URL，见下方说明
CREDENTIAL (
  USERNAME = 'username'
);

如何确定正确的 URL:

1. 在 Hive CLI 或 Beeline 中执行：

   SHOW CREATE TABLE your_db.your_table;
   

2. 查看输出中的 LOCATION 字段，例如：

   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 参数。

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 模式）

-- 创建 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'
);

场景 5：启用 Kerberos，且 HDFS 为高可用（HA）

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'
);

更多关于 Location 参数配置，请参见 CREATE EXTERNAL TABLE 中的 LOCATION 章节及 Catalog 与外部表。

配置说明与注意事项

• 认证分离：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 与外部表
• 通过 Catalog 加载 Iceberg 表
• Hive 表（HMS）
• Catalog 概述
• 部署 OceanBase 数据库 JAVA SDK 环境
• CREATE EXTERNAL CATALOG