创建 Catalog

本文将向您介绍如何使用 SQL 语句创建 External Catalog。

权限要求

创建 External Catalog，需要当前用户拥有 CREATE CATALOG 权限。有关 OceanBase 数据库权限的详细介绍，参见 MySQL 模式下的权限分类。

语法

创建 External Catalog 的 SQL 语句格式如下：

CREATE EXTERNAL CATALOG [IF NOT EXISTS] external_catalog_name
    PROPERTIES [=] (properties_type_options);

properties_type_options:
    odps_type_list
    | hms_type_list

odps_type_list:
    TYPE = 'ODPS',
    [ACCESSTYPE = 'accesstype_string',]
    ACCESSID = 'string',
    ACCESSKEY = 'string',
    STSTOKEN = 'string',
    ENDPOINT = 'string',
    TUNNEL_ENDPOINT = 'string',
    PROJECT_NAME = 'string',
    [QUOTA_NAME = 'string',]
    [COMPRESSION = 'compression_string',]
    REGION = 'string'

hms_type_list:
    TYPE = 'HMS',
    URI = "string"
    [, KRB5CONF = "string"]
    [, KEYTAB = "string"]
    [, PRINCIPAL = "string"]
    [, MAX_CLIENT_POOL_SIZE = 20]
    [, SOCKET_TIMEOUT = 10000000]

accesstype_string:
    aliyun
    | sts
    | app

compression_string:
    zlib
    | zstd
    | lz4
    | odps_lz4

参数说明：

• IF NOT EXISTS：可选项，如果指定该子句，即使要创建的外部数据目录在当前租户中已存在，也不会报错，系统会提示一条 Warning 信息；如果不指定，则会报错。
• external_catalog_name：表示要创建的外部数据目录的名称。
• PROPERTIES [=] (properties_type_options)：用于指定外部数据目录类型的相关属性选项。
• odps_type_list：表示 ODPS 类型外部数据目录（ODPS Catalog）的相关属性列表。
• hms_type_list：表示 HMS 类型外部数据目录（HMS Catalog）的相关属性列表。

有关创建 External Catalog 语法的详细参数说明信息，参见 CREATE EXTERNAL CATALOG。

创建 ODPS 类型的 External Catalog

外表读写 MaxCompute 数据时，取值为 ODPS。

通过 CREATE EXTERNAL CATALOG 创建与 MaxCompute（ODPS）的连接，实现直接查询 ODPS 表数据，无需手动创建映射表。Catalog 下对象为只读；向 MaxCompute 写入数据请使用 ODPS 外部表。

示例如下：

obclient> CREATE EXTERNAL CATALOG test_odps_catalog
    PROPERTIES = (
        TYPE = 'ODPS',
        ACCESSID = '$odps_accessid',
        ACCESSKEY = '$odps_accesskey',
        ENDPOINT = '$odps_endpoint',
        TUNNEL_ENDPOINT = 'http://xxx.maxcompute.aliyun.com',
        PROJECT_NAME = 'mysqltest_regression_sqlqa',
        QUOTA_NAME = '',
        COMPRESSION_CODE = ''
    );

创建 HMS 类型的 External Catalog

OceanBase 数据库通过 HMS Catalog 功能，实现对 Hive 元数据（Metastore）的统一管理。通过 HMS Catalog，OceanBase 可直接访问 Hive 表对应的 HDFS 存储路径中的数据，支持高效的数据湖查询与分析。

HMS Catalog 支持情况

当前版本 HMS Catalog 支持 Hive 和 Iceberg 两种表格式，支持读取 Hive 和 Iceberg 的统计信息，优化 SQL Plan。

Hive 格式支持情况

当前版本支持 Parquet、ORC、Textfile、OpenCSV 四种格式。

Hive 版本支持

OceanBase 当前支持以下 Hive 版本的 HMS Catalog：

• Hive 1.2.x
• Hive 2.3.x
• Hive 3.1.x
• Hive 4.x

Iceberg 支持情况

当前版本支持 Iceberg V1、V2 和 V3 版本。

OceanBase 数据库支持读取 Schema Evolution 和 Partition Transform 过的 Iceberg 表。

Iceberg 支持 Deletion vector，Iceberg 表 V3 版本基于行级删除的变更：

• 在 V3 版本中引入了 Deletion vector，并通过 Puffin deletion-vector-v1 blob 类型进行存储。

• Manifests 得到更新以追踪 Deletion vector：

  • 新增了 referenced_data_file 字段，既可用于 Deletion vector（必需），也可用于仅包含一个数据文件删除的 V2 position delete file（可选）。
  • 新增了 content_offset 字段，必须与 Deletion vector blob 在 Puffin 文件中的 offset 相对应。
  • 新增了 content_size_in_bytes 字段，必须与 Deletion vector blob 在 Puffin 文件中的长度相对应。

• Deletion vector 需要同步维护：写入端必须合并 DV（以及早期的 position delete file），从而确保每个 data file 最多对应一个 DV。

  • 如果数据文件存在 DV，读取端可以安全地忽略 position delete file。

• 写入端不允许向 V3 表中添加新的 position delete file。

• 现有的 position delete file 在从 V2 升级的表中依然有效。

  • 当为某个 data file 创建 DV 时，必须将这些 position delete file 合并进该 DV。
  • 如果 position delete file 包含了对多个 data file 的删除，则这些文件需要在表的元数据中保留，直到所有的删除操作都被 DV 替代。
  • 即表从 V2 升级到 V3 后，原本的 Position Delete Files 仍然有效，会继续被查询时参考。但 当某个数据文件首次生成 Deletion Vector（DV）时，针对该文件的所有 Position Delete 记录会被合并到对应的 DV 中。此后，该文件的删除信息完全由 DV 管理，原有的 Position Delete Files 中与此文件相关的部分可以被清理（前提是这些 Position Delete Files 不包含其他文件的删除记录）。

认证类型支持

OceanBase 数据库支持以下两种 HMS Catalog 认证方式：

示例如下：

• 创建 SIMPLE 认证的 HMS Catalog，普通认证模式，不需要设置 Location 认证。

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

• 创建 Kerberos 认证 HMS Catalog。

  obclient> CREATE EXTERNAL CATALOG test_hms_catalog_kerberos
      PROPERTIES = (
          TYPE = 'HMS',
          URI = "thrift://xxx.xxx.xxx.xxx:xxxx",
          PRINCIPAL = "hive/xxx@xxx.COM",
          KEYTAB = "/xxx/xxx/xxx/hadoop.keytab",
          KRB5CONF = "/etc/xxx.conf"
      );
  

Location 认证

OceanBase 数据库 HMS Catalog 支持通过 External Location 进行密钥管理，实现对外部存储的安全访问。当访问 HMS 中的表时，系统会根据表路径自动匹配对应的 External Location，如果能匹配到则使用其密钥进行认证访问。

Location 认证场景

根据存储类型和安全要求，Location 认证分为以下几种场景：

配置步骤

1. 确定 Location 认证场景。

   根据存储类型和安全要求，选择对应的认证场景。

2. 创建 Location 对象。

   使用 CREATE LOCATION 语句创建对应场景的 Location 对象。有关创建 Location 的详细介绍，参见 CREATE LOCATION。

3. 关联 Catalog。

   创建 Catalog 时无需额外配置，系统会自动根据对应表的存储路径来匹配 Location。

Location 认证场景配置示例

OSS 存储认证

创建一个适用于阿里云 OSS 对象存储访问的 Location 对象。

CREATE LOCATION oss_credential
    URL = 'oss://bucket-name/path'
    CREDENTIAL = (
        ACCESSID = 'your-access-key-id'
        ACCESSKEY = 'your-access-key-secret'
        HOST = 'oss-region.aliyuncs.com'
    );

HDFS 存储认证

• 场景 1：无认证模式。

  无需创建 Location，适用于 HDFS 集群未启用 Kerberos 认证（即 hadoop.security.authentication=simple）的开发或测试环境。

• 场景 2：用户认证模式。

  无需 Kerberos，但需以特定 HDFS 用户身份访问。

  说明

  适用于未开启 Kerberos 权限认证的集群，但相关 HDFS 路径需要特定用户才能访问的场景。

  创建 Location：指定 HDFS 用户。

  CREATE LOCATION hdfs_user01
      URL = 'hdfs://namenode:8020/'
      CREDENTIAL (
          USER = 'hdfs_user_name'
      );
  

• 场景 3：启用 Kerberos，HDFS 为单 NameNode（非 HA 模式）。

  说明

  CONFIGS 中的 dfs.data.transfer.protection 必须与 HDFS 集群配置一致。

  创建 Location：Kerberos 认证 + 单点 HDFS。

  CREATE LOCATION hdfs_kerberos_single
      URL = 'hdfs://namenode.example.com:8020/'
      CREDENTIAL (
          PRINCIPAL = "hdfs/xxx@xxx.COM",
          KEYTAB = "/data/hdfs.keytab",
          KRB5CONF = "/data/krb5.conf",
          CONFIGS = 'dfs.data.transfer.protection=integrity'
      );
  

• 场景 4：启用 Kerberos，HDFS 为高可用（HA）模式。

  CREATE LOCATION hdfs_kerberos_ha
      URL = 'hdfs://${nameservice id}'
      CREDENTIAL (
          PRINCIPAL = "hdfs/xxx@xxx.COM",
          KEYTAB = "/etc/ob/hdfs.keytab",
          KRB5CONF = "/etc/krb5.conf",
          CONFIGS = 'dfs.data.transfer.protection=${string}#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'
          );
  

• 场景 5：未启用 Kerberos，但 HDFS 为高可用（HA）模式。

  说明

  未启用 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'
          );
  

相关文档

• Catalog 概述
• 查看 Catalog
• 删除 Catalog
• CREATE EXTERNAL CATALOG