バージョン: 4.1 GA

Hudi catalog

Hudi catalog は、Apache Hudi からデータを取り込まずにクエリを実行できる外部 catalog の一種です。

また、Hudi catalogs に基づいて INSERT INTO を使用して、Hudi からデータを直接変換してロードすることもできます。

Hudi クラスターでの SQL ワークロードを成功させるためには、StarRocks クラスターが Hudi クラスターのストレージシステムとメタストアにアクセスできる必要があります。StarRocks は以下のストレージシステムとメタストアをサポートしています。

AWS S3、Microsoft Azure Storage、Google GCS などのオブジェクトストレージ
Hive メタストアや AWS Glue のようなメタストア

NOTE

ストレージとして AWS S3 を選択した場合、メタストアとして HMS または AWS Glue を使用できます。他のストレージシステムを選択した場合、メタストアとして HMS のみを使用できます。

使用上の注意

StarRocks がサポートする Hudi のファイル形式は Parquet です。Parquet ファイルは以下の圧縮形式をサポートしています: SNAPPY、LZ4、ZSTD、GZIP、NO_COMPRESSION。
StarRocks は Hudi の Copy On Write (COW) テーブルと Merge On Read (MOR) テーブルを完全にサポートしています。

統合準備

Hudi catalog を作成する前に、StarRocks クラスターが Hudi クラスターのストレージシステムとメタストアと統合できることを確認してください。

Hive メタストア

Hudi クラスターがメタストアとして Hive メタストアを使用している場合、PhoenixAI が Hive メタストアのホストにアクセスできることを確認してください。

注記

通常、PhoenixAI クラスターと Hive メタストアの統合を有効にするために、以下のいずれかのアクションを実行できます。

PhoenixAI クラスターと Hive メタストアを同じ VPC にデプロイする。
PhoenixAI クラスターの VPC と Hive メタストアの VPC の間に VPC ピアリング接続を構成する。

次に、Hive メタストアのセキュリティグループの設定を確認し、そのインバウンドルールが PhoenixAI クラスターのセキュリティグループからのインバウンドトラフィックを許可し、そのポート範囲がデフォルトポート 9083 をカバーしていることを確認してください。

AWS IAM

Hudi クラスターが AWS S3 をストレージとして使用する場合、または AWS Glue をメタストアとして使用する場合、適切な認証方法を選択し、StarRocks クラスターが関連する AWS クラウドリソースにアクセスできるように必要な準備を行ってください。

以下の認証方法が推奨されます。

インスタンスプロファイル
アサインされたロール
IAM ユーザー

上記の3つの認証方法の中で、インスタンスプロファイルが最も広く使用されています。

詳細については、AWS IAM での認証準備を参照してください。

Microsoft Azure Storage

Hudi クラスターがストレージとして Azure を使用している場合、適切な認証方法を選択し、ロールの割り当ての追加など、必要な準備を行います。詳細については、Azure クラウドストレージへの認証を参照してください。

Hudi catalog の作成

構文

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "hudi",
    MetastoreParams,
    StorageCredentialParams,
    MetadataUpdateParams
)

パラメータ

catalog_name

Hudi catalog の名前です。命名規則は次のとおりです。

名前には文字、数字 (0-9)、アンダースコア (_) を含めることができます。文字で始める必要があります。
名前は大文字と小文字を区別し、長さは1023文字を超えてはいけません。

comment

Hudi catalog の説明です。このパラメータはオプションです。

type

データソースのタイプです。値を hudi に設定します。

MetastoreParams

StarRocks がデータソースのメタストアと統合する方法に関する一連のパラメータです。

Hive メタストア

データソースのメタストアとして Hive メタストアを選択した場合、MetastoreParams を次のように設定します。

"hive.metastore.type" = "hive",
"hive.metastore.uris" = "<hive_metastore_uri>"

次の表は、MetastoreParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
hive.metastore.type	Yes	Hudi クラスターで使用するメタストアのタイプです。値を `hive` に設定します。
hive.metastore.uris	Yes	Hive メタストアの URI です。形式: `thrift://<metastore_IP_address>:<metastore_port>`。 Hive メタストアで高可用性 (HA) が有効になっている場合、複数のメタストア URI を指定し、カンマ (`,`) で区切ることができます。例: `"thrift://<metastore_IP_address_1>:<metastore_port_1>,thrift://<metastore_IP_address_2>:<metastore_port_2>,thrift://<metastore_IP_address_3>:<metastore_port_3>"`。

AWS Glue

データソースのメタストアとして AWS Glue を選択した場合、これは AWS S3 をストレージとして選択した場合にのみサポートされます。次のいずれかの操作を行います。

インスタンスプロファイルベースの認証方法を選択する場合、MetastoreParams を次のように設定します。
```
"hive.metastore.type" = "glue",
"aws.glue.use_instance_profile" = "true",
"aws.glue.region" = "<aws_glue_region>"
```

アサインされたロールベースの認証方法を選択する場合、MetastoreParams を次のように設定します。

"hive.metastore.type" = "glue",
"aws.glue.use_instance_profile" = "true",
"aws.glue.iam_role_arn" = "<iam_role_arn>",
"aws.glue.region" = "<aws_glue_region>"

IAM ユーザーベースの認証方法を選択する場合、MetastoreParams を次のように設定します。

"hive.metastore.type" = "glue",
"aws.glue.use_instance_profile" = "false",
"aws.glue.access_key" = "<iam_user_access_key>",
"aws.glue.secret_key" = "<iam_user_secret_key>",
"aws.glue.region" = "<aws_s3_region>"

次の表は、MetastoreParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
hive.metastore.type	Yes	Hudi クラスターで使用するメタストアのタイプです。値を `glue` に設定します。
aws.glue.use_instance_profile	Yes	インスタンスプロファイルベースの認証方法とアサインされたロールベースの認証方法を有効にするかどうかを指定します。有効な値: `true` と `false`。デフォルト値: `false`。
aws.glue.iam_role_arn	No	AWS Glue Data Catalog に対する権限を持つ IAM ロールの ARN です。AWS Glue にアクセスするためにアサインされたロールベースの認証方法を使用する場合、このパラメータを指定する必要があります。
aws.glue.region	Yes	AWS Glue Data Catalog が存在するリージョンです。例: `us-west-1`。
aws.glue.access_key	No	AWS IAM ユーザーのアクセスキーです。IAM ユーザーベースの認証方法を使用して AWS Glue にアクセスする場合、このパラメータを指定する必要があります。
aws.glue.secret_key	No	AWS IAM ユーザーのシークレットキーです。IAM ユーザーベースの認証方法を使用して AWS Glue にアクセスする場合、このパラメータを指定する必要があります。

AWS Glue にアクセスするための認証方法の選択方法や AWS IAM コンソールでのアクセス制御ポリシーの設定方法については、AWS Glue へのアクセスのための認証パラメータを参照してください。

StorageCredentialParams

StarRocks がストレージシステムと統合する方法に関する一連のパラメータです。

AWS S3、Microsoft Azure Storage、または Google GCS をストレージとして使用する場合、StorageCredentialParams を設定する必要があります。

AWS S3

Hudi クラスターのストレージとして AWS S3 を選択した場合、次のいずれかの操作を行います。

インスタンスプロファイルベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。
```
"aws.s3.use_instance_profile" = "true",
"aws.s3.region" = "<aws_s3_region>"
```
アサインされたロールベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。
```
"aws.s3.use_instance_profile" = "true",
"aws.s3.iam_role_arn" = "<iam_role_arn>",
"aws.s3.region" = "<aws_s3_region>"
```

IAM ユーザーベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"aws.s3.use_instance_profile" = "false",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>",
"aws.s3.region" = "<aws_s3_region>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
aws.s3.use_instance_profile	Yes	インスタンスプロファイルベースの認証方法とアサインされたロールベースの認証方法を有効にするかどうかを指定します。有効な値: `true` と `false`。デフォルト値: `false`。
aws.s3.iam_role_arn	No	AWS S3 バケットに対する権限を持つ IAM ロールの ARN です。AWS S3 にアクセスするためにアサインされたロールベースの認証方法を使用する場合、このパラメータを指定する必要があります。
aws.s3.region	Yes	AWS S3 バケットが存在するリージョンです。例: `us-west-1`。
aws.s3.access_key	No	IAM ユーザーのアクセスキーです。IAM ユーザーベースの認証方法を使用して AWS S3 にアクセスする場合、このパラメータを指定する必要があります。
aws.s3.secret_key	No	IAM ユーザーのシークレットキーです。IAM ユーザーベースの認証方法を使用して AWS S3 にアクセスする場合、このパラメータを指定する必要があります。

AWS S3 にアクセスするための認証方法の選択方法や AWS IAM コンソールでのアクセス制御ポリシーの設定方法については、AWS S3 へのアクセスのための認証パラメータを参照してください。

Microsoft Azure Storage

このセクションでは、さまざまな Azure クラウドストレージサービスとさまざまな認証方法を使用して統合するために StorageCredentialParams で設定する必要があるパラメータについて説明します。これらのパラメータの値を取得する方法については、Azure クラウドストレージへの認証を参照してください。

Azure Blob Storage

Blob Storage を Hudi クラスターのストレージとして選択した場合、次のいずれかの操作を行います。

共有キー認証方法を選択する場合、StorageCredentialParams を次のように設定します。
```
"azure.blob.storage_account" = "<storage_account_name>",
"azure.blob.shared_key" = "<storage_account_shared_key>"
```
次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter Required Description
azure.blob.storage_account Yes Blob Storage アカウントの名前です。
azure.blob.shared_key Yes Blob Storage アカウントの共有キーです。

SAS トークン認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"azure.blob.storage_account" = "<storage_account_name>",
"azure.blob.container" = "<container_name>",
"azure.blob.sas_token" = "<storage_account_SAS_token>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
azure.blob.storage_account	Yes	Blob Storage アカウントの名前です。
azure.blob.container	Yes	データを格納する blob コンテナの名前です。
azure.blob.sas_token	Yes	Blob Storage アカウントにアクセスするために使用される SAS トークンです。

Azure Data Lake Storage Gen2

Data Lake Storage Gen2 を Hudi クラスターのストレージとして選択した場合、次のいずれかの操作を行います。

マネージド ID 認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"azure.adls2.oauth2_use_managed_identity" = "true",
"azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
"azure.adls2.oauth2_client_id" = "<service_client_id>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
azure.adls2.oauth2_use_managed_identity	Yes	マネージド ID 認証方法を有効にするかどうかを指定します。値を `true` に設定します。
azure.adls2.oauth2_tenant_id	Yes	アクセスしたいデータのテナント ID です。
azure.adls2.oauth2_client_id	Yes	マネージド ID のクライアント (アプリケーション) ID です。

注記

マネージドアイデンティティは PhoenixAI クラスターのデプロイに使用されたものでなければならず、そのクライアント ID はデスティネーション PhoenixAI クラスターのデータクレデンシャルで参照されるものです。マネージドアイデンティティには、ストレージアカウントに対する必要な読み取りおよび書き込み権限（例：Storage Blob Data Owner）を割り当てる必要があります。認証に使用するストレージアカウントは、Hudi クラスターのデータを保存するために使用されるものでなければなりません。

共有キー認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"azure.adls2.storage_account" = "<storage_account_name>",
"azure.adls2.shared_key" = "<storage_account_shared_key>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
azure.adls2.storage_account	Yes	Data Lake Storage Gen2 ストレージアカウントの名前です。
azure.adls2.shared_key	Yes	Data Lake Storage Gen2 ストレージアカウントの共有キーです。

サービスプリンシパル認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"azure.adls2.oauth2_client_id" = "<service_client_id>",
"azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
"azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
azure.adls2.oauth2_client_id	Yes	サービスプリンシパルのクライアント (アプリケーション) ID です。
azure.adls2.oauth2_client_secret	Yes	作成された新しいクライアント (アプリケーション) シークレットの値です。
azure.adls2.oauth2_client_endpoint	Yes	サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント (v1) です。

注記

サービスプリンシパルは PhoenixAI クラスターのデプロイに使用されたものでなければならず、ストレージアカウントに対する必要な読み取りおよび書き込み権限（例：Storage Blob Data Owner）を割り当てる必要があります。認証に使用するストレージアカウントは、Hudi クラスターのデータを保存するために使用されるものでなければなりません。

Azure Data Lake Storage Gen1

Data Lake Storage Gen1 を Hudi クラスターのストレージとして選択した場合、次のいずれかの操作を行います。

マネージドサービス ID 認証方法を選択する場合、StorageCredentialParams を次のように設定します。
```
"azure.adls1.use_managed_service_identity" = "true"
```
次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter Required Description
azure.adls1.use_managed_service_identity Yes マネージドサービス ID 認証方法を有効にするかどうかを指定します。値を true に設定します。

Parameter	Required	Description
azure.adls1.use_managed_service_identity	Yes	マネージドサービス ID 認証方法を有効にするかどうかを指定します。値を `true` に設定します。

サービスプリンシパル認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"azure.adls1.oauth2_client_id" = "<application_client_id>",
"azure.adls1.oauth2_credential" = "<application_client_credential>",
"azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Required	Description
azure.adls1.oauth2_client_id	Yes	サービスプリンシパルのクライアント (アプリケーション) ID です。
azure.adls1.oauth2_credential	Yes	作成された新しいクライアント (アプリケーション) シークレットの値です。
azure.adls1.oauth2_endpoint	Yes	サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント (v1) です。

注記

Google GCS

Google GCS を Hudi クラスターのストレージとして選択した場合、次のいずれかの操作を行います。

VM ベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"gcp.gcs.use_compute_engine_service_account" = "true"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Default value	Value example	Description
gcp.gcs.use_compute_engine_service_account	false	true	コンピュートエンジンにバインドされたサービスアカウントを直接使用するかどうかを指定します。

サービスアカウントベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
"gcp.gcs.service_account_private_key" = "<google_service_private_key>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Default value	Value example	Description
gcp.gcs.service_account_email	""	"user@hello.iam.gserviceaccount.com"	サービスアカウントの作成時に生成された JSON ファイルのメールアドレスです。
gcp.gcs.service_account_private_key_id	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	サービスアカウントの作成時に生成された JSON ファイルのプライベートキー ID です。
gcp.gcs.service_account_private_key	""	"-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"	サービスアカウントの作成時に生成された JSON ファイルのプライベートキーです。

インパーソネーションベースの認証方法を選択する場合、StorageCredentialParams を次のように設定します。

VM インスタンスがサービスアカウントをインパーソネートする場合:

"gcp.gcs.use_compute_engine_service_account" = "true",
"gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Default value	Value example	Description
gcp.gcs.use_compute_engine_service_account	false	true	コンピュートエンジンにバインドされたサービスアカウントを直接使用するかどうかを指定します。
gcp.gcs.impersonation_service_account	""	"hello"	インパーソネートしたいサービスアカウントです。

サービスアカウント (一時的にメタサービスアカウントと呼ばれる) が別のサービスアカウント (一時的にデータサービスアカウントと呼ばれる) をインパーソネートする場合:

"gcp.gcs.service_account_email" = "<google_service_account_email>",
"gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
"gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
"gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"

次の表は、StorageCredentialParams で設定する必要があるパラメータを説明しています。

Parameter	Default value	Value example	Description
gcp.gcs.service_account_email	""	"user@hello.iam.gserviceaccount.com"	メタサービスアカウントの作成時に生成された JSON ファイルのメールアドレスです。
gcp.gcs.service_account_private_key_id	""	"61d257bd8479547cb3e04f0b9b6b9ca07af3b7ea"	メタサービスアカウントの作成時に生成された JSON ファイルのプライベートキー ID です。
gcp.gcs.service_account_private_key	""	"-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"	メタサービスアカウントの作成時に生成された JSON ファイルのプライベートキーです。
gcp.gcs.impersonation_service_account	""	"hello"	インパーソネートしたいデータサービスアカウントです。

MetadataUpdateParams

StarRocks が Hudi のキャッシュされたメタデータを更新する方法に関する一連のパラメータです。このパラメータセットはオプションです。

StarRocks はデフォルトで自動非同期更新ポリシーを実装しています。

ほとんどの場合、MetadataUpdateParams を無視し、その中のポリシーパラメータを調整する必要はありません。これらのパラメータのデフォルト値は、すぐに使用できるパフォーマンスを提供します。

ただし、Hudi でのデータ更新の頻度が高い場合、これらのパラメータを調整して自動非同期更新のパフォーマンスをさらに最適化できます。

NOTE

ほとんどの場合、Hudi データが 1 時間以下の粒度で更新される場合、データ更新の頻度は高いと見なされます。

Parameter	Required	Description
enable_metastore_cache	No	StarRocks が Hudi テーブルのメタデータをキャッシュするかどうかを指定します。有効な値: `true` と `false`。デフォルト値: `true`。値 `true` はキャッシュを有効にし、値 `false` はキャッシュを無効にします。
enable_remote_file_cache	No	StarRocks が Hudi テーブルまたはパーティションの基礎データファイルのメタデータをキャッシュするかどうかを指定します。有効な値: `true` と `false`。デフォルト値: `true`。値 `true` はキャッシュを有効にし、値 `false` はキャッシュを無効にします。
metastore_cache_refresh_interval_sec	No	StarRocks が Hudi テーブルまたはパーティションのキャッシュされたメタデータを非同期で更新する時間間隔です。単位: 秒。デフォルト値: `7200` (2 時間)。
remote_file_cache_refresh_interval_sec	No	StarRocks が Hudi テーブルまたはパーティションの基礎データファイルのキャッシュされたメタデータを非同期で更新する時間間隔です。単位: 秒。デフォルト値: `60`。
metastore_cache_ttl_sec	No	StarRocks が Hudi テーブルまたはパーティションのキャッシュされたメタデータを自動的に破棄する時間間隔です。単位: 秒。デフォルト値: `86400` (24 時間)。
remote_file_cache_ttl_sec	No	StarRocks が Hudi テーブルまたはパーティションの基礎データファイルのキャッシュされたメタデータを自動的に破棄する時間間隔です。単位: 秒。デフォルト値: `129600` (36 時間)。

例

次の例は、使用するメタストアのタイプに応じて、hudi_catalog_hms または hudi_catalog_glue という名前の Hudi catalog を作成し、Hudi クラスターからデータをクエリします。

AWS S3

インスタンスプロファイルベースのクレデンシャルを選択した場合

Hudi クラスターで Hive メタストアを使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "us-west-2"
);

Amazon EMR Hudi クラスターで AWS Glue を使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_glue
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "true",
    "aws.glue.region" = "us-west-2",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.region" = "us-west-2"
);

アサインされたロールベースのクレデンシャルを選択した場合

Hudi クラスターで Hive メタストアを使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
    "aws.s3.region" = "us-west-2"
);

Amazon EMR Hudi クラスターで AWS Glue を使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_glue
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "true",
    "aws.glue.iam_role_arn" = "arn:aws:iam::081976408565:role/test_glue_role",
    "aws.glue.region" = "us-west-2",
    "aws.s3.use_instance_profile" = "true",
    "aws.s3.iam_role_arn" = "arn:aws:iam::081976408565:role/test_s3_role",
    "aws.s3.region" = "us-west-2"
);

IAM ユーザーベースのクレデンシャルを選択した場合

Hudi クラスターで Hive メタストアを使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_access_key>",
    "aws.s3.region" = "us-west-2"
);

Amazon EMR Hudi クラスターで AWS Glue を使用する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_glue
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "glue",
    "aws.glue.use_instance_profile" = "false",
    "aws.glue.access_key" = "<iam_user_access_key>",
    "aws.glue.secret_key" = "<iam_user_secret_key>",
    "aws.glue.region" = "us-west-2",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>",
    "aws.s3.region" = "us-west-2"
);

Microsoft Azure Storage

Azure Blob Storage

共有キー認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.shared_key" = "<blob_storage_account_shared_key>"
);

SAS トークン認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.blob.storage_account" = "<blob_storage_account_name>",
    "azure.blob.container" = "<blob_container_name>",
    "azure.blob.sas_token" = "<blob_storage_account_SAS_token>"
);

Azure Data Lake Storage Gen1

マネージドサービス ID 認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls1.use_managed_service_identity" = "true"    
);

サービスプリンシパル認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls1.oauth2_client_id" = "<application_client_id>",
    "azure.adls1.oauth2_credential" = "<application_client_credential>",
    "azure.adls1.oauth2_endpoint" = "<OAuth_2.0_authorization_endpoint_v2>"
);

Azure Data Lake Storage Gen2

マネージド ID 認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.oauth2_use_managed_identity" = "true",
    "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
    "azure.adls2.oauth2_client_id" = "<service_client_id>"
);

共有キー認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.storage_account" = "<storage_account_name>",
    "azure.adls2.shared_key" = "<shared_key>"     
);

サービスプリンシパル認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.oauth2_client_id" = "<service_client_id>",
    "azure.adls2.oauth2_client_secret" = "<service_principal_client_secret>",
    "azure.adls2.oauth2_client_endpoint" = "<service_principal_client_endpoint>"
);

Google GCS

VM ベースの認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "gcp.gcs.use_compute_engine_service_account" = "true"    
);

サービスアカウントベースの認証方法を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "gcp.gcs.service_account_email" = "<google_service_account_email>",
    "gcp.gcs.service_account_private_key_id" = "<google_service_private_key_id>",
    "gcp.gcs.service_account_private_key" = "<google_service_private_key>"    
);

インパーソネーションベースの認証方法を選択する場合:

VM インスタンスがサービスアカウントをインパーソネートする場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "gcp.gcs.use_compute_engine_service_account" = "true",
    "gcp.gcs.impersonation_service_account" = "<assumed_google_service_account_email>"    
);

サービスアカウントが別のサービスアカウントをインパーソネートする場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG hudi_catalog_hms
PROPERTIES
(
    "type" = "hudi",
    "hive.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "gcp.gcs.service_account_email" = "<google_service_account_email>",
    "gcp.gcs.service_account_private_key_id" = "<meta_google_service_account_email>",
    "gcp.gcs.service_account_private_key" = "<meta_google_service_account_email>",
    "gcp.gcs.impersonation_service_account" = "<data_google_service_account_email>"    
);

Hudi catalogs の表示

現在の StarRocks クラスター内のすべての catalog をクエリするには、SHOW CATALOGS を使用できます。

SHOW CATALOGS;

また、外部 catalog の作成ステートメントをクエリするには、SHOW CREATE CATALOG を使用できます。次の例では、hudi_catalog_glue という名前の Hudi catalog の作成ステートメントをクエリします。

SHOW CREATE CATALOG hudi_catalog_glue;

Hudi Catalog とその中のデータベースに切り替える

Hudi catalog とその中のデータベースに切り替えるには、次のいずれかの方法を使用できます。

現在のセッションで Hudi catalog を指定するには SET CATALOG を使用し、その後 USE を使用してアクティブなデータベースを指定します。

-- 現在のセッションで指定された catalog に切り替える:
SET CATALOG <catalog_name>
-- 現在のセッションでアクティブなデータベースを指定する:
USE <db_name>

直接 USE を使用して、Hudi catalog とその中のデータベースに切り替えます。
```
USE <catalog_name>.<db_name>
```

Hudi catalog の削除

外部 catalog を削除するには、DROP CATALOG を使用できます。

次の例では、hudi_catalog_glue という名前の Hudi catalog を削除します。

DROP Catalog hudi_catalog_glue;

Hudi テーブルのスキーマを表示する

Hudi テーブルのスキーマを表示するには、次のいずれかの構文を使用できます。

スキーマを表示

DESC[RIBE] <catalog_name>.<database_name>.<table_name>

CREATE ステートメントからスキーマと場所を表示

SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>

Hudi テーブルをクエリする

Hudi クラスター内のデータベースを表示するには、SHOW DATABASES を使用します。
```
SHOW DATABASES FROM <catalog_name>
```
Hudi Catalog とその中のデータベースに切り替える。
指定されたデータベース内の宛先テーブルをクエリするには、SELECT を使用します。
```
SELECT count(*) FROM <table_name> LIMIT 10
```

Hudi からデータをロードする

olap_tbl という名前の OLAP テーブルがあると仮定して、次のようにデータを変換してロードできます。

INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM hudi_table

メタデータキャッシュを手動または自動で更新する

手動更新

デフォルトでは、StarRocks は Hudi のメタデータをキャッシュし、非同期モードでメタデータを自動的に更新して、より良いパフォーマンスを提供します。さらに、Hudi テーブルでいくつかのスキーマ変更やテーブル更新が行われた後、REFRESH EXTERNAL TABLE を使用してメタデータを手動で更新することもできます。これにより、StarRocks が最新のメタデータをできるだけ早く取得し、適切な実行プランを生成できるようにします。

REFRESH EXTERNAL TABLE <table_name> [PARTITION ('partition_name', ...)]

付録: メタデータ自動非同期更新を理解する

自動非同期更新は、StarRocks が Hudi catalogs のメタデータを更新するために使用するデフォルトのポリシーです。

デフォルトでは (enable_metastore_cache と enable_remote_file_cache パラメータが両方とも true に設定されている場合)、クエリが Hudi テーブルのパーティションにヒットすると、StarRocks はそのパーティションのメタデータとそのパーティションの基礎データファイルのメタデータを自動的にキャッシュします。キャッシュされたメタデータは、遅延更新ポリシーを使用して更新されます。

たとえば、table2 という名前の Hudi テーブルがあり、4 つのパーティション p1、p2、p3、p4 を持っているとします。クエリが p1 にヒットすると、StarRocks は p1 のメタデータと p1 の基礎データファイルのメタデータをキャッシュします。キャッシュされたメタデータを更新および破棄するデフォルトの時間間隔は次のとおりです。

p1 のキャッシュされたメタデータを非同期で更新する時間間隔 (metastore_cache_refresh_interval_sec パラメータで指定) は 2 時間です。
p1 の基礎データファイルのキャッシュされたメタデータを非同期で更新する時間間隔 (remote_file_cache_refresh_interval_sec パラメータで指定) は 60 秒です。
p1 のキャッシュされたメタデータを自動的に破棄する時間間隔 (metastore_cache_ttl_sec パラメータで指定) は 24 時間です。
p1 の基礎データファイルのキャッシュされたメタデータを自動的に破棄する時間間隔 (remote_file_cache_ttl_sec パラメータで指定) は 36 時間です。

次の図は、キャッシュされたメタデータの更新と破棄の時間間隔をタイムラインで示しています。

キャッシュされたメタデータの更新と破棄のタイムライン

その後、StarRocks は次のルールに従ってメタデータを更新または破棄します。

別のクエリが再び p1 にヒットし、最後の更新からの現在の時間が 60 秒未満の場合、StarRocks は p1 のキャッシュされたメタデータや p1 の基礎データファイルのキャッシュされたメタデータを更新しません。
別のクエリが再び p1 にヒットし、最後の更新からの現在の時間が 60 秒を超える場合、StarRocks は p1 の基礎データファイルのキャッシュされたメタデータを更新します。
別のクエリが再び p1 にヒットし、最後の更新からの現在の時間が 2 時間を超える場合、StarRocks は p1 のキャッシュされたメタデータを更新します。
p1 が最後の更新から 24 時間以内にアクセスされていない場合、StarRocks は p1 のキャッシュされたメタデータを破棄します。メタデータは次のクエリでキャッシュされます。
p1 が最後の更新から 36 時間以内にアクセスされていない場合、StarRocks は p1 の基礎データファイルのキャッシュされたメタデータを破棄します。メタデータは次のクエリでキャッシュされます。

Parameter	Required	Description
azure.blob.storage_account	Yes	Blob Storage アカウントの名前です。
azure.blob.shared_key	Yes	Blob Storage アカウントの共有キーです。

使用上の注意​

統合準備​

Hive メタストア​

AWS IAM​

Microsoft Azure Storage​

Hudi catalog の作成​

構文​

パラメータ​

catalog_name​

comment​

type​

MetastoreParams​

Hive メタストア​

AWS Glue​

StorageCredentialParams​

AWS S3​

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

Google GCS​

MetadataUpdateParams​

例​

AWS S3​

インスタンスプロファイルベースのクレデンシャルを選択した場合​

アサインされたロールベースのクレデンシャルを選択した場合​

IAM ユーザーベースのクレデンシャルを選択した場合​

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen1​

Azure Data Lake Storage Gen2​

Google GCS​

Hudi catalogs の表示​

Hudi Catalog とその中のデータベースに切り替える​

Hudi catalog の削除​

Hudi テーブルのスキーマを表示する​

Hudi テーブルをクエリする​

Hudi からデータをロードする​

メタデータキャッシュを手動または自動で更新する​

手動更新​

付録: メタデータ自動非同期更新を理解する​

使用上の注意

統合準備

Hive メタストア

AWS IAM

Microsoft Azure Storage

Hudi catalog の作成

構文

パラメータ

catalog_name

comment

type

MetastoreParams

Hive メタストア

AWS Glue

StorageCredentialParams

AWS S3

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

Google GCS

MetadataUpdateParams

例

AWS S3

インスタンスプロファイルベースのクレデンシャルを選択した場合

アサインされたロールベースのクレデンシャルを選択した場合

IAM ユーザーベースのクレデンシャルを選択した場合

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen1

Azure Data Lake Storage Gen2

Google GCS

Hudi catalogs の表示

Hudi Catalog とその中のデータベースに切り替える

Hudi catalog の削除

Hudi テーブルのスキーマを表示する

Hudi テーブルをクエリする

Hudi からデータをロードする

メタデータキャッシュを手動または自動で更新する

手動更新

付録: メタデータ自動非同期更新を理解する