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 などのカタログ関連権限を持っている必要があります（MySQLモード）。カタログ機能は現在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）へのアクセスには、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）がディレクトリの権限を持つユーザー/グループに含まれていない場合は、必ず：

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はデフォルトで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'
);

正しい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（メタデータ）と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