HMS Catalog

OceanBaseはV4.4.1バージョンからHMS（Hive Metastore）接続をサポートし、HMS Catalogを作成することで、Hive Metastoreが管理するテーブル（従来のHiveテーブルやIceberg形式で保存されているがメタデータはHive Metastoreに登録されているテーブルを含む）への統一的なアクセスを実現します。ユーザーはデータ移行を行うことなく、Hadoopエコシステム内でHMSが管理するデータを直接クエリでき、データレイクのクエリ高速化シナリオに適しています。

• メタデータの統一管理：Hive Metastoreを通じてテーブル構造を自動同期します。
• フェデレーションクエリ：OceanBaseの内部テーブルとJOINして分析します。
• 読み取り専用の安全性：誤操作によるソースデータの変更を防ぎます。

OceanBaseはV4.4.1バージョンからHMS Catalog機能を正式にサポートしています。本ドキュメントは、ユーザーが事前にOceanBaseデータベースのAP能力を理解し計画するためのものであり、関連する使用方法は既にV4.3.5のドキュメント集で提供されています。

サポート機能

• 読み取り専用アクセス：すべてのHMS Catalog下のオブジェクトは読み取り専用であり、現在はINSERT、UPDATE、DROP TABLEなどのDML/DDL操作をサポートしていません。

• 対応テーブルタイプ：

  • Hiveテーブル：ORC、Parquet、TextFile、CSV。

    • 複合型では、現バージョンではParquet形式のARRAY型のみがサポートされています。
    • ARRAY型の詳細については、配列要素型の概要を参照してください。

  • Icebergテーブル：V1 / V2バージョン、Parquet形式を推奨します。

• 高度な機能：

  • Iceberg Schema Evolution（列の追加・削除）
  • Iceberg Partition Transform（bucket()、year()などのパーティション式）

• Hiveバージョン互換性

  • サポートバージョン：Hive 1.2.x、Hive 2.3.x、Hive 3.1.x、Hive 4.x。
  • 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テーブルを認識し、読み取ります。

      したがって、IcebergテーブルのメタデータがHive Metastoreに正しく登録されていれば（どのエンジンによって書き込まれたものであっても）、OceanBaseはアクセス可能です。

前提条件

1. 環境依存関係：基盤ストレージがHDFSの場合、事前にJava SDK環境をデプロイする必要があります。 詳細については、OceanBase JAVA SDK環境のデプロイを参照してください。

2. 権限要件

   • HMSサービス：OceanBaseクラスタはHive Metastore（Thriftプロトコル）にアクセスできる必要があります。 HMSサービスのアドレスとポートは、お客様の運用チームから提供されるものとします。オープンソースのHiveはデフォルトでポート9083を使用しますが、実際のデプロイでは異なる場合があります。現場の設定を優先してください。

   • ストレージシステム：すべてのOBServerノードはHDFS/S3/OSSに対して読み取り可能である必要があります。

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

パラメータ説明

SIMPLE認証のHMS Catalogを作成する

通常認証モードでは、Location認証の設定は不要です。

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

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

ステップ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）へのアクセスには、2つの独立した認証レイヤーが関わります：

• Catalog層：Hive Metastoreに接続し（テーブル構造、パーティションなどのメタデータを取得するために使用されます）。

• Location層：実際にHDFSなどのファイルシステムに保存されているデータファイルを読み取るために使用されます。

これら2つの認証方式は別々に設定する必要があり、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サーバーはクライアントが宣言するOSユーザー名を信頼し、パスワードや資格情報の検証は行いません。権限制御は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）がディレクトリの許可ユーザー/グループに含まれていない場合は、次の操作が必要です：

  • Locationを作成し、権限を持つユーザーを指定します：

    CREATE LOCATION my_loc URI = 'hdfs://mycluster/'
    CREDENTIAL = (USER = '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はデフォルトでOSユーザー（例：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'  -- HDFSへのアクセスユーザー名を指定
);

正しい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 hms_krb
    PROPERTIES (
      'type' = 'hms',
      'hive.metastore.uris' = 'thrift://metastore:9083',
      'authentication' = 'KERBEROS',
      'kerberos.principal' = 'ob@REALM',
      'kerberos.keytab' = '/path/to/ob.keytab',
      'kerberos.krb5.conf' = '/etc/krb5.conf'
    );
  

• HDFS Location：

  CREATE LOCATION hdfs_krb_loc
    URI = 'hdfs://nn:8020',
    CREDENTIAL = (
      KERBEROS = (
        PRINCIPAL = 'ob@REALM',
        KEYTAB = '/path/to/ob.keytab',
        KRB5CONF = '/etc/krb5.conf'
      )
    );
  

シナリオ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'
);

設定の説明と注意点

• 認証分離：Catalog（メタデータ）とLocation（データ）の認証は、別々に設定します。
• モードの整合性：OceanBaseの認証方式は、Hadoopクラスタのhadoop.security.authentication設定と一致している必要があります。
• Kerberosの強制整合性：HMSまたはHDFSでKerberosが有効な場合、両方でKerberos資格情報を設定する必要があります。
• SIMPLEモードでは権限に注意：Observerユーザーまたは指定されたUSERがHDFSパスに対する読み取り権限を持っていることを確認してください。

関連ドキュメント

• Catalogの概要
• OceanBase Java SDK環境のデプロイ
• CREATE EXTERNAL CATALOG