通过 HMS Catalog 访问 Hive 表

OceanBase AI 数据库支持通过 Hive Metastore（HMS）创建 HMS Catalog，统一访问已在 HMS 中注册的 Hive 表。HMS 负责提供库、表、分区等元数据；表数据仍存放在 HDFS、S3 及兼容 S3 协议的对象存储等外部存储中。

本文说明如何创建 HMS Catalog、配置存储访问认证，以及查询 Hive 表并与内表进行联邦分析。

访问模型

通过 HMS 访问 Hive 表时，OceanBase 的执行过程分为两步：

1. 读取元数据：通过 HMS Catalog 连接 Hive Metastore，获取 Hive 库、表、分区及存储路径等信息。
2. 读取数据文件：根据 HMS 返回的 LOCATION 等信息，从外部存储读取 ORC、Parquet 等格式的数据文件。

访问链路涉及三层：

• HMS 是元数据服务，不是数据存储位置。
• Hive 表的数据文件存放在 HMS 元数据中记录的 LOCATION 路径下。
• Catalog 权限与存储读权限相互独立：具备 Catalog 权限不代表一定能读取底层文件。

若 Hive 表数据位于权限受限的 HDFS 路径，或集群启用了 Kerberos，需分别配置 HMS Catalog 与 Location。

支持能力

支持的操作

表类型与 Hive 版本

• 支持表类型：Hive 表，即 HMS Catalog 的原生表类型。
• Hive 版本：支持 Hive 1.2.x、2.3.x、3.1.x、4.x。不同版本下表定义与存储路径格式可能存在差异，以 HMS 中实际元数据为准。
• HMS Catalog 名称：Hive Metastore 3.x 起支持在 HMS 内维护多个 Catalog。连接此类 HMS 时，可通过 HMS_CATALOG_NAME 指定要访问的 Catalog；未指定时由 HMS 按默认行为处理，3.x 及以上默认 Catalog 名称通常为 hive。

文件格式与查询支持

在 HMS 元数据与存储访问正常的前提下，OceanBase 对 Hive 表查询支持：

• 分区裁剪：在 WHERE 中指定分区列时，可缩小扫描范围。
• 列裁剪：仅读取 SELECT 涉及的列（取决于文件格式）。
• 谓词下推：部分过滤条件下推至文件读取层（以执行计划为准）。

与 Iceberg 的关系

HMS Catalog 也可访问元数据注册在 Hive Metastore 中的 Iceberg 表，但 Iceberg 表的详细能力、Catalog 类型差异及写入边界参见 [通过 Catalog 加载 Iceberg 表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000006326202)。简要说明如下：

• Hive 4.x 及以上：Hive 引擎原生支持 Iceberg 表，OceanBase 可直接通过 HMS Catalog 访问。
• Hive 1.2.x / 2.3.x / 3.1.x：Hive 本身不支持 Iceberg；此类环境中 Iceberg 表通常由 Spark、Flink 等引擎创建并将元数据注册到 HMS，OceanBase 依赖 HMS 中的元数据识别和读取。

前提条件

1. 权限：当前用户需具备 CREATE CATALOG、USE CATALOG 等 Catalog 相关权限。
2. HMS 服务：OceanBase AI 数据库集群需能访问 Hive Metastore（Thrift 协议）。HMS 地址与端口由运维侧提供；开源 Hive 默认端口为 9083，实际部署可能不同。
3. 存储访问：所有 OBServer 节点对 Hive 表底层存储（HDFS、S3 及兼容 S3 协议的对象存储等）具备读权限。
4. 环境依赖：底层存储为 HDFS 时，需提前部署 Java SDK 环境，参见 部署 OceanBase AI 数据库JAVA SDK 环境。
5. 认证配置：若 HDFS 路径权限受限或集群启用 Kerberos，需分别配置 HMS Catalog（元数据层）与 Location（数据层）。

操作步骤

下文示例统一使用 OceanBase 侧 Catalog 名称 hive_prod（与 HMS 内的 HMS_CATALOG_NAME 不是同一个）。请按现场环境替换 URI、库表名及凭据路径。

操作前请确认：认证选型

访问 Hive 表涉及 Catalog 层（连 HMS） 与 Location 层（读存储文件） 两层认证，需分别配置。动手创建 Catalog / Location 前，请向 Hadoop 运维确认集群安全模式，并对照下表选择路径：

按上述确认结果，选择 HDFS 场景的 Location 配置路径（S3 场景参见 CREATE EXTERNAL CATALOG 中的具体示例）：

操作顺序：

1. 完成 Java SDK 部署。
2. 创建 HMS Catalog（步骤 1）。
3. 按场景创建 Location（步骤 2，部分场景可跳过）。
4. 验证元数据与存储连通（步骤 3）。
5. 查询或联邦分析（步骤 4、5）。

步骤 1：创建 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 认证示例

普通认证模式，Catalog 层无需 Kerberos 参数；HDFS 读权限按场景决定是否需要 Location。

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

Kerberos 认证示例（元数据层）

CREATE EXTERNAL CATALOG hive_prod
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：（可选）创建 Location

当 Hive 表数据位于需显式指定操作系统用户或 Kerberos 凭据的 HDFS 路径时，创建 Location。Kerberos 环境下示例如下（数据层）：

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 等配置见下文认证章节
);

SIMPLE 模式下受限路径示例：

CREATE LOCATION hdfs_sales
URL = 'hdfs://namenode:8020/'
CREDENTIAL (
    USERNAME = 'hive'
);

如何确定 Location 的 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，即 hdfs://namenode:8020/

Location 如何与 Catalog 关联：

创建 Catalog 时无需手动绑定 Location。查询 Hive 表时，OceanBase 先从 HMS 获取表的 LOCATION，再按 URL 前缀自动匹配已创建的 Location；匹配成功则使用该 Location 中的凭据访问底层文件，未匹配则按默认方式访问（SIMPLE 模式下等价于 Observer 进程用户身份）。

因此，Location 的 URL 应能覆盖目标表 LOCATION 的前缀。例如表路径为 hdfs://namenode:8020/warehouse/sales.db/t1，Location 的 URL 可设为 hdfs://namenode:8020/。

步骤 3：验证连通性

创建 Catalog（及按需创建的 Location）后，先验证元数据与存储是否可达，再执行大范围扫描查询。

-- 切换到 HMS Catalog
SET CATALOG hive_prod;

-- 验证 HMS 元数据是否可读（失败多为 Catalog 层 / HMS 连通问题）
DESC hive_prod.sales_db.customer_log;

-- 可选：查看 HMS 侧表定义
SHOW CREATE TABLE hive_prod.sales_db.customer_log;

-- 小范围试查，验证存储层读权限（失败多为 Location / HDFS 权限问题）
SELECT * FROM sales_db.customer_log
WHERE dt = '20250401'
LIMIT 10;

步骤 4：查询 Hive 表

验证通过后，可按以下两种方式查询（若已在步骤 3 执行 SET CATALOG，方式一可省略第一行）。

方式一：切换会话上下文

SET CATALOG hive_prod;
USE sales_db;

SELECT * FROM customer_log
WHERE dt = '20250401'
LIMIT 100;

方式二：使用三段式标识符

SELECT city, COUNT(*)
FROM hive_prod.sales_db.customer_log
WHERE dt >= '2025-04-01'
GROUP BY city;

步骤 5：联邦查询（可选）

SELECT o.order_id, h.city
FROM internal.trade_db.orders o
JOIN hive_prod.sales_db.customer h ON o.user_id = h.id;

更多查询示例（可选）

分区表查询

Hive 分区表的分区信息由 HMS 提供。查询时在 WHERE 子句中指定分区列，OceanBase 可下推分区裁剪：

SET CATALOG hive_prod;
USE sales_db;

SELECT product_id, SUM(amount)
FROM sales_detail
WHERE dt = '20250401' AND region = 'cn-east'
GROUP BY product_id;

查看表结构

DESC hive_prod.sales_db.sales_detail;

SHOW CREATE TABLE hive_prod.sales_db.sales_detail;

Iceberg 表查询（经 HMS 注册）

若 HMS 中注册了 Iceberg 表，可通过同一 HMS Catalog 查询（能力边界见 通过 Catalog 加载 Iceberg 表）：

SET CATALOG hive_prod;

SELECT product_id, SUM(sales)
FROM iceberg_db.sales_iceberg
WHERE event_time >= '2025-04-01'
GROUP BY product_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：所有客户端（含 HMS Client、HDFS Client）须通过 Kerberos 身份验证。
• simple：服务端信任客户端声明的操作系统用户名；权限控制基于 HDFS 文件/目录的属主、属组及 POSIX 权限位（如 drwxr-xr-x），无 Kerberos 身份认证。

OceanBase 的认证配置方式

重要配置规则：HMS 或 HDFS 任一启用 Kerberos 时，请检查两层凭据是否均已正确部署。

SIMPLE 模式详解

适用场景：

• HDFS 未启用 Kerberos，依赖 Linux 文件权限控制。
• 表由特定用户写入（如 Impala 写入路径属主为 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）不属于 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。

场景 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 与外部表。

注意事项与限制

1. 只读访问：HMS Catalog 下 Hive 表均为只读，不支持 INSERT、UPDATE、DROP TABLE 等 DML/DDL，也不支持修改 HMS 侧表结构。
2. 认证分离：Catalog（元数据）与 Location（数据）认证独立配置；HMS 连接失败与 HDFS 读权限不足是两类不同问题，需分别排查。
3. 模式对齐：OceanBase 认证方式须与 Hadoop 集群 hadoop.security.authentication 一致；HMS 或 HDFS 启用 Kerberos 时，两层均须配置 Kerberos 凭据。
4. SIMPLE 模式权限：确保 Observer 进程用户或 Location 中指定的 USERNAME 对 HDFS 路径具备读权限。
5. HMS Catalog 名称：HMS 3.1.3 及以上若存在多个 Catalog，创建时须确认 HMS_CATALOG_NAME 与 HMS 侧实际名称一致。