Catalogを使用してIcebergテーブルをロードする

Apache Icebergはオープンソースのテーブル形式（Lake Table Format）であり、テーブルのデータファイルとメタデータファイルは外部ストレージ（OSS、S3、HDFSなど）に保存されます。Catalogはテーブルの名前空間とメタデータポインタを管理します。

OceanBaseは**External Catalog（外部カタログ）**を通じて外部Catalogサービス（例：HMS Catalog、REST Catalog）に接続し、対応するCatalogからIcebergテーブルのメタデータをロードした後、基盤となるデータファイルを読み取ります。Icebergテーブルは単純なファイルパスから直接アクセスすることはできません。Catalogがmetadata.json、snapshot、manifestなどのメタデータ情報を提供する必要があります。

Icebergシステムにおける各概念の役割分担は以下のとおりです：

OceanBaseは、オブジェクトストレージのディレクトリ構造を直接解析してIcebergテーブルを「検出」するわけではありません。代わりに、External Catalogを通じて外部Catalogサービスからテーブル定義を取得し、メタデータに基づいてデータファイルを特定して読み取ります。

サポート機能

• サポートタイプ

  Icebergは新世代のオープンテーブル形式仕様です。HMS Catalogは拡張を通じてHiveメタデータでIcebergテーブルを管理し、統一されたメタデータエントリを実現します。

  各CatalogタイプのCREATE EXTERNAL CATALOG構文とパラメータについては、CREATE EXTERNAL CATALOGおよび現在のバージョンの製品ドキュメントを参照してください。

• 上級機能

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

前提条件

1. バージョンとモード：MySQLモードのテナント。HMS CatalogからIcebergテーブルにアクセスする場合、OceanBaseはV4.4.1以降である必要があります（HMS Catalogの設定については、Catalogを使用したHiveテーブルのロードを参照してください）。
2. Icebergテーブルの準備：対象のIcebergテーブルが対応するCatalogに登録されており、メタデータが完全に利用可能であること。
3. ストレージアクセス：すべてのOBServerノードがIcebergテーブルのwarehouseパスに対する読み取り権限を持っていること。HDFSを使用する場合はJava SDKをデプロイする必要があります。OceanBaseデータベースJAVA SDK環境のデプロイを参照してください。
4. Catalogサービスへのアクセス可能性：OceanBaseクラスタのネットワークがHMS Thriftエンドポイント、REST Catalogサービスのアドレス、またはオブジェクトストレージ/ファイルシステムのパスにアクセス可能であること。
5. 権限：現在のユーザーがCREATE CATALOG、USE CATALOGなどの権限を持っていること。ストレージ層でKerberosまたはAccessKeyが必要な場合は、LocationまたはCatalog資格情報を追加で設定する必要があります。

IcebergテーブルにアクセスするためのExternal Catalogの作成

HMS Catalogを使用したロード

IcebergテーブルのメタデータがHive Metastoreに存在する場合、TYPE = 'HMS'のExternal Catalogを作成します：

CREATE EXTERNAL CATALOG iceberg_hms
PROPERTIES (
    TYPE = 'HMS',
    URI = 'thrift://hms.example.com:9083'
);

作成手順、Kerberos認証、Location設定については、Catalogを使用したHiveテーブルのロードを参照してください。

REST Catalogを使用したロード

REST CatalogはHTTP APIを通じてIcebergメタデータを提供します。External Catalogを作成する際には、CatalogタイプをRESTと指定し、RESTサービスのアドレス、warehouse、認証情報などのパラメータを設定する必要があります。

CREATE EXTERNAL CATALOG iceberg_rest
PROPERTIES (
    TYPE = 'REST',
    URI = '<rest_catalog_api_endpoint>',
    WAREHOUSE = '<warehouse_name_or_path>'
    -- その他のパラメータはCREATE EXTERNAL CATALOG構文ドキュメントに準ずる
);

REST Catalogの完全なパラメータリスト（OAuth2認証、WAREHOUSE形式など）は、RESTサービスの実装によって異なります。詳細については、CREATE EXTERNAL CATALOGドキュメントを参照してください。

Icebergテーブルのクエリ

Catalogの切り替え

SET CATALOG iceberg_hms;
USE analytics_db;

または、3部構成の識別子を使用することで、コンテキスト切り替えが不要です：

SELECT * FROM iceberg_hms.analytics_db.events
WHERE event_date = '2025-04-01'
LIMIT 100;

クエリ例

-- 集計クエリ
SELECT product_id, SUM(sales_amount)
FROM iceberg_hms-analytics_db_sales
WHERE event_time >= '2025-04-01'
GROUP BY product_id;

-- 内部テーブルとの連携クエリ
SELECT o.order_id, e.event_type
FROM internal_trade_db.orders o
JOIN iceberg_hms-analytics_db.events e ON o.user_id = e.user_id;

メタデータの確認

SHOW CATALOGS;

DESC iceberg_hms.analytics_db.sales;

SHOW CREATE TABLE iceberg_hms.analytics_db.sales;

Icebergテーブルのサポート機能

以下の機能は、External Catalogを介してアクセスされるIcebergテーブルに適用されます。HMS CatalogまたはREST Catalogによって読み込まれた場合、Icebergテーブルがサポートする機能と列型は一致します。主な違いは、メタデータをどのCatalogサービスから取得するかです。書き込み機能など、バージョンやCatalogタイプによって異なる場合は、現在のバージョンの動作を優先します。

読み取り機能

書き込み機能

データファイル形式

Icebergテーブルの基盤となるデータファイル形式は主にParquetです。メタデータファイルにはmetadata.json、manifest、manifest-listなどが含まれ、OceanBaseがクエリ時に解析します。

注意事項

1. Catalogとストレージの区別：Catalogはメタデータマッピングを提供しますが、データファイル自体はOSS、S3、HDFSなどの外部ストレージにあります。ストレージの資格情報は別途設定する必要があります。
2. テーブル形式とファイル形式の区別：Icebergはテーブル形式です。Parquetはその基盤となる一般的なファイル形式です。両者を混同して表現してはいけません。
3. HMS内のIcebergテーブル：Hive 1.2.x / 2.3.x / 3.1.x自体はIcebergをネイティブで管理しませんが、Spark/FlinkなどのエンジンがIcebergメタデータをHMSに登録している場合、OceanBaseはHMS Catalogを通じてアクセスできます。Catalogを使用したHiveテーブルのロードのIceberg互換性説明を参照してください。
4. Catalogに登録されていないファイル：オブジェクトストレージ上の裸のParquet/ORCファイルはIcebergテーブルではありません。ファイル外部テーブルを使用してアクセスしてください。
5. 機能の範囲：REST、FILESYSTEM Catalogのパラメータと動作は、製品の現在のバージョンドキュメントに準じます。本記事に記載されていないIceberg機能は、デフォルトで現在のバージョンではサポートされていない、または別途確認が必要なものと見なされます。

関連ドキュメント

• データレイクの概要
• Catalogと外部テーブル
• Catalogを使用したHiveテーブルのロード
• Hiveテーブル（HMS）
• CREATE EXTERNAL CATALOG