Hudi Catalog

Hudi Catalog は Hive Catalog を再利用します。Hive Metastore または Hive Metastore と互換性のあるメタデータサービスに接続することで、Doris は Hudi のデータベースとテーブルの情報を自動的に取得し、データをクエリできます。

Apache Doris と Apache Hudi のクイックスタート。

適用シナリオ

シナリオ	説明
クエリの高速化	Doris の分散コンピューティングエンジンから Hudi データに直接アクセスし、クエリを高速化します。
データ統合	Hudi データを読み取って Doris の内部テーブルに書き込むか、Doris のコンピューティングエンジンを使用して ZeroETL 処理を行います。
データの書き戻し	サポートされていません。

Catalog の設定

構文

CREATE CATALOG [IF NOT EXISTS] catalog_name PROPERTIES (
    'type' = 'hms', -- required
    'hive.metastore.uris' = '<metastore_thrift_url>', -- required
    {MetaStoreProperties},
    {StorageProperties},
    {HudiProperties},
    {CommonProperties}
);

• [MetaStoreProperties]

  MetaStoreProperties には、Metastore メタデータサービスへの接続情報と認証情報を指定します。詳しくは「[サポートされるメタデータサービス]」を参照してください。

• [StorageProperties]

  StorageProperties には、ストレージシステムへの接続情報と認証情報を指定します。詳しくは「[サポートされるストレージシステム]」を参照してください。

• [CommonProperties]

  CommonProperties には共通プロパティを指定します。詳しくは Data Catalog の概要 の「[共通プロパティ]」を参照してください。

• {HudiProperties}

  パラメータ名	旧名称	説明	デフォルト値
  hudi.use_hive_sync_partition	use_hive_sync_partition	Hive Metastore に同期済みのパーティション情報を使用するかどうかを指定します。true の場合は Hive Metastore から直接取得し、それ以外の場合はファイルシステム上のメタデータファイルから取得します。Hive Metastore からの取得は効率的ですが、最新のメタデータが Hive Metastore に同期されていることをユーザーが確認する必要があります。	false

メタデータキャッシュ

Apache Doris は、外部データソースへのアクセス性能を高めるために Hudi のメタデータをキャッシュします。対象には、テーブル構造（Schema）、パーティション情報、FS View、Meta Client オブジェクトが含まれます。

ヒント

Doris 4.1.x より前のバージョンでは、メタデータキャッシュは主に FE の設定項目でグローバルに制御します。詳しくは メタデータキャッシュ を参照してください。 Doris 4.1.x 以降では、Hudi 関連の外部メタデータキャッシュを共通の meta.cache.* キーで設定します。

キャッシュプロパティの設定（4.1.x 以降）

Hudi のキャッシュエントリには、meta.cache.hudi.<entry>.{enable,ttl-second,capacity} 形式の設定キーを使用します。現在、Hudi のエントリは件数で上限を設定し、エントリ単位の max-weight は指定できません。詳しくは 外部メタデータキャッシュのメモリ管理 を参照してください。

プロパティ	例	意味
enable	true/false	このキャッシュモジュールを有効にするかどうか。
ttl-second	600, 0, -1	0 はキャッシュを無効にし（直ちに反映され、最新データの確認に使用できます）、-1 は期限切れなしを意味します。それ以外の正の整数は、アクセス時刻を基準とする TTL（秒）です。
capacity	10000	キャッシュエントリの最大件数。0 は無効を意味します。

有効になる条件： モジュールのキャッシュは、enable=true、ttl-second != 0、capacity > 0 のすべてを満たす場合にのみ有効になります。

キャッシュモジュール

Hudi Catalog には次のキャッシュモジュールがあります。

モジュール（<entry>）	プロパティキーのプレフィックス	キャッシュされる内容と影響
schema	meta.cache.hudi.schema.	テーブル構造をキャッシュします。影響：テーブルの列情報が反映されるタイミングに関係します。無効にすると、各クエリで最新の Schema を取得します。
partition	meta.cache.hudi.partition.	Hudi のパーティション関連メタデータをキャッシュします。影響：パーティションの検出とプルーニングに使用します。
fs_view	meta.cache.hudi.fs_view.	Hudi のファイルシステムビューに関するメタデータをキャッシュします。
meta_client	meta.cache.hudi.meta_client.	Hudi Meta Client オブジェクトをキャッシュします。影響：Hudi メタデータの重複した読み込みを減らします。

旧パラメータとの対応と変換

バージョン 4.1.x 以降では、共通キーの使用を推奨します。旧 Catalog プロパティと 4.1.x 以降の共通キーの対応は次のとおりです。

旧プロパティキー	4.1.x 以降の共通キー	説明
schema.cache.ttl-second	meta.cache.hudi.schema.ttl-second	テーブル構造キャッシュの有効期限

ベストプラクティス

• 最新データへのリアルタイムアクセス：各クエリで Hudi テーブルの最新のデータ変更またはスキーマ変更を確認するには、ttl-second を schema または partition で 0 に設定できます。

  -- Disable partition metadata cache to detect the latest partition changes in Hudi tables
  ALTER CATALOG hudi_ctl SET PROPERTIES ("meta.cache.hudi.partition.ttl-second" = "0");
• 性能の最適化：Doris 4.1.4 以降では、Catalog のプロパティ変更が成功すると、Catalog の実行コンテキストがリセットされ、その Catalog が使用するすべてのメタデータキャッシュエンジンの初期化済みエントリがクリアされます。次回のアクセス時に、新しいコンテキストと設定を使用して再構築されます。実行中のクエリには影響しません。

可観測性

キャッシュのメトリクスは、information_schema.catalog_meta_cache_statistics システムテーブルで確認できます。

SELECT catalog_name, engine_name, entry_name,
       effective_enabled, ttl_second, capacity,
       estimated_size, hit_rate, load_failure_count, last_error
FROM information_schema.catalog_meta_cache_statistics
WHERE catalog_name = 'hudi_ctl' AND engine_name = 'hudi'
ORDER BY entry_name;

このシステムテーブルについては、catalog_meta_cache_statistics を参照してください。

サポートされる Hudi のバージョン

現在依存している Hudi のバージョンは 0.15 です。Hudi データのバージョンは 0.14 以降を推奨します。

サポートされるクエリの種類

テーブルの種類	サポートされるクエリの種類
Copy On Write	スナップショットクエリ、タイムトラベル、増分読み取り
Merge On Read	スナップショットクエリ、読み取り最適化クエリ、タイムトラベル、増分読み取り

サポートされるメタデータサービス

• Hive Metastore

サポートされるストレージシステム

• HDFS
• AWS S3
• Google Cloud Storage
• Alibaba Cloud OSS
• Tencent Cloud COS
• Huawei Cloud OBS
• MINIO

サポートされるデータ形式

• Parquet
• ORC

列の型のマッピング

Hudi の型	Doris の型	備考
boolean	boolean
int	int
long	bigint
float	float
double	double
decimal(P, S)	decimal(P, S)
bytes	string
string	string
date	date
timestamp	datetime(N)	精度に応じて datetime(3) または datetime(6) に自動的にマッピングされます
array	array
map	map
struct	struct
other	UNSUPPORTED

例

Hudi Catalog の作成方法は Hive Catalog と同様です。ほかの例については、Hive Catalog を参照してください。

CREATE CATALOG hudi_hms PROPERTIES (
    'type'='hms',
    'hive.metastore.uris' = 'thrift://172.21.0.1:7004',
    'hadoop.username' = 'hive',
    'dfs.nameservices'='your-nameservice',
    'dfs.ha.namenodes.your-nameservice'='nn1,nn2',
    'dfs.namenode.rpc-address.your-nameservice.nn1'='172.21.0.2:4007',
    'dfs.namenode.rpc-address.your-nameservice.nn2'='172.21.0.3:4007',
    'dfs.client.failover.proxy.provider.your-nameservice'='org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider'
);

クエリ操作

基本的なクエリ

Catalog を設定したら、次の方法で Catalog 内のテーブルをクエリできます。

-- 1. switch to catalog, use database and query
SWITCH hudi_ctl;
USE hudi_db;
SELECT * FROM hudi_tbl LIMIT 10;

-- 2. use hudi database directly
USE hudi_ctl.hudi_db;
SELECT * FROM hudi_tbl LIMIT 10;

-- 3. use full qualified name to query
SELECT * FROM hudi_ctl.hudi_db.hudi_tbl LIMIT 10;

タイムトラベル

Hudi テーブルへの書き込み操作ごとに新しいスナップショットが作成されます。Doris は Hudi テーブルの指定したスナップショットの読み取りをサポートします。デフォルトでは、クエリは最新のスナップショットのみを読み取ります。

hudi_meta() テーブル関数を使用すると、指定した Hudi テーブルのタイムラインをクエリできます。

このテーブル関数は 3.1.0 以降でサポートされています。

SELECT * FROM hudi_meta(
    'table' = 'hudi_ctl.hudi_db.hudi_tbl',
    'query_type' = 'timeline'
);

+-------------------+--------+--------------------------+-----------+-----------------------+
| timestamp         | action | file_name                | state     | state_transition_time |
+-------------------+--------+--------------------------+-----------+-----------------------+
| 20241202171214902 | commit | 20241202171214902.commit | COMPLETED | 20241202171215756     |
| 20241202171217258 | commit | 20241202171217258.commit | COMPLETED | 20241202171218127     |
| 20241202171219557 | commit | 20241202171219557.commit | COMPLETED | 20241202171220308     |
| 20241202171221769 | commit | 20241202171221769.commit | COMPLETED | 20241202171222541     |
| 20241202171224269 | commit | 20241202171224269.commit | COMPLETED | 20241202171224995     |
| 20241202171226401 | commit | 20241202171226401.commit | COMPLETED | 20241202171227155     |
| 20241202171228827 | commit | 20241202171228827.commit | COMPLETED | 20241202171229570     |
| 20241202171230907 | commit | 20241202171230907.commit | COMPLETED | 20241202171231686     |
| 20241202171233356 | commit | 20241202171233356.commit | COMPLETED | 20241202171234288     |
| 20241202171235940 | commit | 20241202171235940.commit | COMPLETED | 20241202171236757     |
+-------------------+--------+--------------------------+-----------+-----------------------+

スナップショットのタイムスタンプを指定し、FOR TIME AS OF 文で過去のデータを読み取れます。時刻の形式は Hudi のドキュメントと同じです。例を次に示します。

SELECT * FROM hudi_tbl FOR TIME AS OF "2022-10-07 17:20:37";
SELECT * FROM hudi_tbl FOR TIME AS OF "20221007172037";
SELECT * FROM hudi_tbl FOR TIME AS OF "2022-10-07";

Hudi テーブルは FOR VERSION AS OF 文をサポートしていません。Hudi テーブルにこの構文を使用するとエラーになります。

増分クエリ

増分読み取りでは、指定した期間内のデータ変更をクエリし、その期間の終了時点でのデータの最終状態を返します。

Doris は、増分読み取り用の @incr 構文を提供します。

SELECT * from hudi_table@incr('beginTime'='xxx', ['endTime'='xxx'], ['hoodie.read.timeline.holes.resolution.policy'='FAIL'], ...);

• beginTime

  必須です。時刻の形式は Hudi 公式ドキュメントの hudi_table_changes と同じで、"earliest" も指定できます。

• endTime

  省略可能です。デフォルトは最新の commitTime です。

@incr 関数には、Spark の読み取りオプション と互換性のあるオプションを追加できます。

desc で実行計画を確認すると、Doris が @incr を VHUDI_SCAN_NODE にプッシュダウンする述語へ変換していることが分かります。

|   0:VHUDI_SCAN_NODE(113)                                                                                            |
|      table: lineitem_mor                                                                                            |
|      predicates: (_hoodie_commit_time[#0] > '20240311151019723'), (_hoodie_commit_time[#0] <= '20240311151606605') |
|      inputSplitNum=1, totalFileSize=13099711, scanRanges=1              

よくある質問

1. Java SDK を使用して JNI 経由で増分データを読み取ると、クエリがブロックされます。

   -Djol.skipHotspotSAAttach=true を JAVA_OPTS_FOR_JDK_17 または JAVA_OPTS（be.conf 内）に追加してください。

付録

変更履歴

Doris のバージョン	サポートされる機能
2.1.8/3.0.4	Hudi の依存バージョンが 0.15 に更新され、Hadoop Hudi JNI Scanner が追加されました。