バージョン: 4.0

Unified catalog

Beta feature

Unified catalogは、StarRocks が v3.2 以降で提供する外部カタログの一種で、Apache Hive™、Apache Iceberg、Apache Hudi、Delta Lake、Apache Kudu のデータソースをインジェストなしで統合データソースとして扱います。Unified catalogを使用すると、次のことが可能です：

Hive、Iceberg、Hudi、Delta Lake、Paimon、Kudu に保存されたデータを手動でテーブルを作成することなく直接クエリできます。
INSERT INTO または非同期マテリアライズドビュー（v2.5 以降でサポート）を使用して、Hive、Iceberg、Hudi、Delta Lake、Paimon、Kudu に保存されたデータを処理し、StarRocks にデータをロードできます。
StarRocks 上で操作を行い、Hive および Iceberg のデータベースやテーブルを作成または削除できます。

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

分散ファイルシステム (HDFS) または AWS S3、Microsoft Azure Storage、Google GCS、その他の S3 互換ストレージシステム（例：MinIO）などのオブジェクトストレージ
Hive メタストアや AWS Glue などのメタストア

注意

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

制限事項

1 つのUnified catalogは、単一のストレージシステムと単一のメタストアサービスとのみ統合をサポートします。したがって、StarRocks と統合したいすべてのデータソースが同じストレージシステムとメタストアサービスを使用していることを確認してください。

使用上の注意

サポートされているファイル形式とデータ型を理解するために、Hive カタログ、Iceberg カタログ、Hudi カタログ、Delta Lake カタログ、Paimon カタログ、および Kudu カタログの「使用上の注意」セクションを参照してください。
形式固有の操作は特定のテーブル形式にのみサポートされています。例えば、CREATE TABLE と DROP TABLE は Hive と Iceberg のみでサポートされており、REFRESH EXTERNAL TABLE は Hive と Hudi のみでサポートされています。

Unified catalog内で CREATE TABLE ステートメントを使用してテーブルを作成する場合、ENGINE パラメータを使用してテーブル形式（Hive または Iceberg）を指定してください。

統合準備

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

AWS IAM

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

HDFS

ストレージとして HDFS を選択した場合、StarRocks クラスターを次のように構成してください：

（オプション）HDFS クラスターおよび Hive メタストアにアクセスするためのユーザー名を設定します。デフォルトでは、StarRocks は HDFS クラスターおよび Hive メタストアにアクセスするために FE および BE または CN プロセスのユーザー名を使用します。また、各 FE の fe/conf/hadoop_env.sh ファイルの先頭、および各 BE または CN の be/conf/hadoop_env.sh ファイルの先頭に export HADOOP_USER_NAME="<user_name>" を追加することでユーザー名を設定することもできます。これらのファイルでユーザー名を設定した後、各 FE および各 BE または CN を再起動してパラメータ設定を有効にします。StarRocks クラスターごとに 1 つのユーザー名のみを設定できます。
データをクエリする際、StarRocks クラスターの FEs および BEs または CNs は HDFS クライアントを使用して HDFS クラスターにアクセスします。ほとんどの場合、その目的を達成するために StarRocks クラスターを構成する必要はなく、StarRocks はデフォルトの設定を使用して HDFS クライアントを起動します。次の状況でのみ StarRocks クラスターを構成する必要があります：
- HDFS クラスターで高可用性 (HA) が有効になっている場合：HDFS クラスターの hdfs-site.xml ファイルを各 FE の $FE_HOME/conf パス、および各 BE または CN の $BE_HOME/conf パスに追加します。
- HDFS クラスターで View File System (ViewFs) が有効になっている場合：HDFS クラスターの core-site.xml ファイルを各 FE の $FE_HOME/conf パス、および各 BE または CN の $BE_HOME/conf パスに追加します。

注意

クエリを送信した際に不明なホストを示すエラーが返された場合、HDFS クラスターのノードのホスト名と IP アドレスのマッピングを /etc/hosts パスに追加する必要があります。

Kerberos 認証

HDFS クラスターまたは Hive メタストアで Kerberos 認証が有効になっている場合、StarRocks クラスターを次のように構成してください：

各 FE および各 BE または CN で kinit -kt keytab_path principal コマンドを実行して、Key Distribution Center (KDC) から Ticket Granting Ticket (TGT) を取得します。このコマンドを実行するには、HDFS クラスターおよび Hive メタストアにアクセスする権限が必要です。このコマンドを使用して KDC にアクセスすることは時間に敏感です。したがって、このコマンドを定期的に実行するために cron を使用する必要があります。
各 FE の $FE_HOME/conf/fe.conf ファイル、および各 BE または CN の $BE_HOME/conf/be.conf ファイルに JAVA_OPTS="-Djava.security.krb5.conf=/etc/krb5.conf" を追加します。この例では、/etc/krb5.conf は krb5.conf ファイルの保存パスです。必要に応じてパスを変更できます。

Unified catalogの作成

構文

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

パラメータ

catalog_name

Unified catalogの名前。命名規則は次の通りです：

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

comment

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

type

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

MetastoreParams

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

Hive メタストア

統合データソースのメタストアとして Hive メタストアを選択した場合、MetastoreParams を次のように構成します：

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

注意

データをクエリする前に、Hive メタストアノードのホスト名と IP アドレスのマッピングを /etc/hosts パスに追加する必要があります。そうしないと、クエリを開始する際に StarRocks が Hive メタストアにアクセスできない可能性があります。

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

パラメータ	必須	説明
unified.metastore.type	はい	統合データソースに使用するメタストアのタイプ。値を `hive` に設定します。
hive.metastore.uris	はい	Hive メタストアの URI。形式：`thrift://<metastore_IP_address>:<metastore_port>`。高可用性 (HA) が Hive メタストアに対して有効になっている場合、複数のメタストア 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 を次のように構成します：
```
"unified.metastore.type" = "glue",
"aws.glue.use_instance_profile" = "true",
"aws.glue.region" = "<aws_glue_region>"
```

アサムドロールベースの認証方法を選択する場合、MetastoreParams を次のように構成します：

"unified.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 を次のように構成します：

"unified.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 で構成する必要があるパラメータを説明しています。

パラメータ	必須	説明
unified.metastore.type	はい	統合データソースに使用するメタストアのタイプ。値を `glue` に設定します。
aws.glue.use_instance_profile	はい	インスタンスプロファイルベースの認証方法とアサムドロールベースの認証を有効にするかどうかを指定します。有効な値：`true` および `false`。デフォルト値：`false`。
aws.glue.iam_role_arn	いいえ	AWS Glue Data Catalog に対する権限を持つ IAM ロールの ARN。AWS Glue にアクセスするためにアサムドロールベースの認証方法を使用する場合、このパラメータを指定する必要があります。
aws.glue.region	はい	AWS Glue Data Catalog が存在するリージョン。例：`us-west-1`。
aws.glue.access_key	いいえ	AWS IAM ユーザーのアクセスキー。AWS Glue にアクセスするために IAM ユーザーベースの認証方法を使用する場合、このパラメータを指定する必要があります。
aws.glue.secret_key	いいえ	AWS IAM ユーザーのシークレットキー。AWS Glue にアクセスするために IAM ユーザーベースの認証方法を使用する場合、このパラメータを指定する必要があります。

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

StorageCredentialParams

StarRocks がストレージシステムと統合する方法に関する一連のパラメータ。このパラメータセットはオプションです。

ストレージとして HDFS を使用する場合、StorageCredentialParams を構成する必要はありません。

ストレージとして AWS S3、その他の S3 互換ストレージシステム、Microsoft Azure Storage、または Google GCS を使用する場合、StorageCredentialParams を構成する必要があります。

AWS S3

ストレージとして 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 で構成する必要があるパラメータを説明しています。

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

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

S3 互換ストレージシステム

S3 互換ストレージシステム（例：MinIO）をストレージとして選択した場合、StorageCredentialParams を次のように構成して、統合を成功させます：

"aws.s3.enable_ssl" = "false",
"aws.s3.enable_path_style_access" = "true",
"aws.s3.endpoint" = "<s3_endpoint>",
"aws.s3.access_key" = "<iam_user_access_key>",
"aws.s3.secret_key" = "<iam_user_secret_key>"

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

パラメータ	必須	説明
aws.s3.enable_ssl	はい	SSL 接続を有効にするかどうかを指定します。有効な値：`true` および `false`。デフォルト値：`true`。
aws.s3.enable_path_style_access	はい	パススタイルアクセスを有効にするかどうかを指定します。有効な値：`true` および `false`。デフォルト値：`false`。MinIO の場合、値を `true` に設定する必要があります。パススタイル URL は次の形式を使用します：`https://s3.<region_code>.amazonaws.com/<bucket_name>/<key_name>`。例えば、US West (Oregon) リージョンに `DOC-EXAMPLE-BUCKET1` というバケットを作成し、そのバケット内の `alice.jpg` オブジェクトにアクセスしたい場合、次のパススタイル URL を使用できます：`https://s3.us-west-2.amazonaws.com/DOC-EXAMPLE-BUCKET1/alice.jpg`。
aws.s3.endpoint	はい	AWS S3 の代わりに S3 互換ストレージシステムに接続するために使用されるエンドポイント。
aws.s3.access_key	はい	IAM ユーザーのアクセスキー。
aws.s3.secret_key	はい	IAM ユーザーのシークレットキー。

Microsoft Azure Storage

Azure Blob Storage

Blob Storage をストレージとして選択した場合、次のいずれかのアクションを実行します：

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

パラメータ必須説明
azure.blob.storage_account はい Blob Storage アカウントのユーザー名。
azure.blob.shared_key はい 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 で構成する必要があるパラメータを説明しています。

パラメータ	必須	説明
azure.blob.storage_account	はい	Blob Storage アカウントのユーザー名。
azure.blob.container	はい	データを保存する Blob コンテナの名前。
azure.blob.sas_token	はい	Blob Storage アカウントにアクセスするために使用される SAS トークン。

Azure Data Lake Storage Gen2

Data Lake Storage Gen2 をストレージとして選択した場合、次のいずれかのアクションを実行します：

マネージド 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 で構成する必要があるパラメータを説明しています。

パラメータ	必須	説明
azure.adls2.oauth2_use_managed_identity	はい	マネージド ID 認証方法を有効にするかどうかを指定します。値を `true` に設定します。
azure.adls2.oauth2_tenant_id	はい	アクセスしたいデータのテナント ID。
azure.adls2.oauth2_client_id	はい	マネージド ID のクライアント（アプリケーション）ID。

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

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

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

パラメータ	必須	説明
azure.adls2.storage_account	はい	Data Lake Storage Gen2 ストレージアカウントのユーザー名。
azure.adls2.shared_key	はい	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 で構成する必要があるパラメータを説明しています。

パラメータ	必須	説明
azure.adls2.oauth2_client_id	はい	サービスプリンシパルのクライアント（アプリケーション）ID。
azure.adls2.oauth2_client_secret	はい	作成された新しいクライアント（アプリケーション）シークレットの値。
azure.adls2.oauth2_client_endpoint	はい	サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント（v1）。

ワークロード ID 認証方法を選択する場合、StorageCredentialParams を次のように構成します:

"azure.adls2.oauth2_token_file" = "<path_to_token>",
"azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
"azure.adls2.oauth2_client_id" = "<service_client_id>"

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

Parameter	Required	Description
azure.adls2.oauth2_token_file	Yes	Azure ワークロード ID ウェブフックによってポッドにマッピングされた、OAuth2 トークンファイルへの絶対ファイルパス。
azure.adls2.oauth2_tenant_id	Yes	アクセスしたいデータのテナント ID です。
azure.adls2.oauth2_client_id	Yes	ワークロード ID に関連付けられている Azure AD アプリケーション（ユーザー割り当てのマネージド ID またはアプリ登録）のクライアント ID（アプリケーション ID）。

Azure Data Lake Storage Gen1

Data Lake Storage Gen1 をストレージとして選択した場合、次のいずれかのアクションを実行します：

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

パラメータ必須説明
azure.adls1.use_managed_service_identity はいマネージドサービス ID 認証方法を有効にするかどうかを指定します。値を true に設定します。

パラメータ	必須	説明
azure.adls1.use_managed_service_identity	はい	マネージドサービス 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 で構成する必要があるパラメータを説明しています。

パラメータ	必須	説明
azure.adls1.oauth2_client_id	はい	サービスプリンシパルのクライアント（アプリケーション）ID。
azure.adls1.oauth2_credential	はい	作成された新しいクライアント（アプリケーション）シークレットの値。
azure.adls1.oauth2_endpoint	はい	サービスプリンシパルまたはアプリケーションの OAuth 2.0 トークンエンドポイント（v1）。

Google GCS

Google GCS をストレージとして選択した場合、次のいずれかのアクションを実行します：

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

"gcp.gcs.use_compute_engine_service_account" = "true"

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

パラメータ	デフォルト値	値の例	説明
gcp.gcs.use_compute_engine_service_account	false	true	Compute Engine にバインドされたサービスアカウントを直接使用するかどうかを指定します。

サービスアカウントベースの認証方法を選択する場合、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 で構成する必要があるパラメータを説明しています。

パラメータ	デフォルト値	値の例	説明
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 で構成する必要があるパラメータを説明しています。

パラメータ	デフォルト値	値の例	説明
gcp.gcs.use_compute_engine_service_account	false	true	Compute Engine にバインドされたサービスアカウントを直接使用するかどうかを指定します。
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 で構成する必要があるパラメータを説明しています。

パラメータ	デフォルト値	値の例	説明
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 が Hive、Hudi、および Delta Lake のキャッシュされたメタデータを更新する方法に関する一連のパラメータ。このパラメータセットはオプションです。Hive、Hudi、および Delta Lake からキャッシュされたメタデータを更新するポリシーの詳細については、Hive カタログ、Hudi カタログ、および Delta Lake カタログを参照してください。

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

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

パラメータ	必須	説明
enable_metastore_cache	いいえ	StarRocks が Hive、Hudi、または Delta Lake テーブルのメタデータをキャッシュするかどうかを指定します。有効な値：`true` および `false`。デフォルト値：`true`。`true` はキャッシュを有効にし、`false` はキャッシュを無効にします。
enable_remote_file_cache	いいえ	StarRocks が Hive、Hudi、または Delta Lake テーブルまたはパーティションの基礎データファイルのメタデータをキャッシュするかどうかを指定します。有効な値：`true` および `false`。デフォルト値：`true`。`true` はキャッシュを有効にし、`false` はキャッシュを無効にします。
metastore_cache_refresh_interval_sec	いいえ	StarRocks が自身にキャッシュされた Hive、Hudi、または Delta Lake テーブルまたはパーティションのメタデータを非同期で更新する時間間隔。単位：秒。デフォルト値：`7200`（2 時間）。
remote_file_cache_refresh_interval_sec	いいえ	StarRocks が自身にキャッシュされた Hive、Hudi、または Delta Lake テーブルまたはパーティションの基礎データファイルのメタデータを非同期で更新する時間間隔。単位：秒。デフォルト値：`60`。
metastore_cache_ttl_sec	いいえ	StarRocks が自身にキャッシュされた Hive、Hudi、または Delta Lake テーブルまたはパーティションのメタデータを自動的に破棄する時間間隔。単位：秒。デフォルト値：`86400`（24 時間）。
remote_file_cache_ttl_sec	いいえ	StarRocks が自身にキャッシュされた Hive、Hudi、または Delta Lake テーブルまたはパーティションの基礎データファイルのメタデータを自動的に破棄する時間間隔。単位：秒。デフォルト値：`129600`（36 時間）。

PaimonCatalogParams

Paimon Catalog に接続する方法に関する一連のパラメータ。このパラメータセットはオプションです。

パラメータ	必須	説明
paimon.catalog.warehouse	いいえ	Paimon データのウェアハウスストレージパス。

KuduCatalogParams

Kudu Catalog に接続する方法に関する一連のパラメータ。このパラメータセットはオプションです。

パラメータ	必須	説明
kudu.master	いいえ	Kudu マスターアドレスを指定します。デフォルトは `localhost:7051` です。
kudu.schema-emulation.enabled	いいえ	`schema` エミュレーションを有効または無効にするオプションです。デフォルトでは無効（false）で、すべてのテーブルは `default` `schema` に属します。
kudu.schema-emulation.prefix	いいえ	`schema` エミュレーションのプレフィックスは、`kudu.schema-emulation.enabled` = `true` の場合にのみ設定する必要があります。デフォルトのプレフィックスは空文字列です：。

例

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

HDFS

ストレージとして HDFS を使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
);

AWS S3

インスタンスプロファイルベースの認証

Hive メタストアを使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 と共に AWS Glue を使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_glue
PROPERTIES
(
    "type" = "unified",
    "unified.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"
);

アサムドロールベースの認証

Hive メタストアを使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 と共に AWS Glue を使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_glue
PROPERTIES
(
    "type" = "unified",
    "unified.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 ユーザーベースの認証

Hive メタストアを使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 と共に AWS Glue を使用する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_glue
PROPERTIES
(
    "type" = "unified",
    "unified.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"
);

S3 互換ストレージシステム

MinIO を例にとります。次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "aws.s3.enable_ssl" = "true",
    "aws.s3.enable_path_style_access" = "true",
    "aws.s3.endpoint" = "<s3_endpoint>",
    "aws.s3.access_key" = "<iam_user_access_key>",
    "aws.s3.secret_key" = "<iam_user_secret_key>"
);

Microsoft Azure Storage

Azure Blob Storage

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

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls1.use_managed_service_identity" = "true"    
);

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

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.metastore.type" = "hive",
    "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>"
);

ワークロード ID 認証方法を選択する場合、次のようなコマンドを実行します：

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.metastore.type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083",
    "azure.adls2.oauth2_token_file" = "/var/run/secrets/azure/tokens/azure-identity-token",
    "azure.adls2.oauth2_tenant_id" = "<service_principal_tenant_id>",
    "azure.adls2.oauth2_client_id" = "<service_client_id>"
);

Google GCS

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

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

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

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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" = "<google_service_private_key_id>",
    "gcp.gcs.service_account_private_key" = "<google_service_private_key>"    
);

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

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

CREATE EXTERNAL CATALOG unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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 unified_catalog_hms
PROPERTIES
(
    "type" = "unified",
    "unified.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>"    
);

Unified catalogの表示

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

SHOW CATALOGS;

外部カタログの作成ステートメントをクエリするには、SHOW CREATE CATALOG を使用できます。次の例では、unified_catalog_glue という名前のUnified catalogの作成ステートメントをクエリします：

SHOW CREATE CATALOG unified_catalog_glue;

Unified catalogとその中のデータベースに切り替える

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

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

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

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

Unified catalogを削除する

外部カタログを削除するには、DROP CATALOG を使用できます。

次の例では、unified_catalog_glue という名前のUnified catalogを削除します：

DROP CATALOG unified_catalog_glue;

Unified catalogからテーブルのスキーマを表示する

Unified catalogからテーブルのスキーマを表示するには、次のいずれかの構文を使用します：

スキーマを表示

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

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

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

Unified catalogからデータをクエリする

Unified catalogからデータをクエリするには、次の手順に従います：

Unified catalogが関連付けられている統合データソース内のデータベースを表示するには、SHOW DATABASES を使用します：
```
SHOW DATABASES FROM <catalog_name>
```
Hive Catalog とその中のデータベースに切り替えます。
指定されたデータベース内の宛先テーブルをクエリするには、SELECT を使用します：
```
SELECT count(*) FROM <table_name> LIMIT 10
```

Hive、Iceberg、Hudi、Delta Lake、または Kudu からデータをロードする

INSERT INTO を使用して、Unified catalog内に作成された StarRocks テーブルに Hive、Iceberg、Hudi、Delta Lake、または Kudu テーブルのデータをロードできます。

次の例では、unified_catalog に属するデータベース test_database に作成された StarRocks テーブル test_tbl に Hive テーブル hive_table のデータをロードします：

INSERT INTO unified_catalog.test_database.test_table SELECT * FROM hive_table

Unified catalogにデータベースを作成する

StarRocks の内部カタログと同様に、Unified catalogで CREATE DATABASE 権限を持っている場合、そのカタログにデータベースを作成するために CREATE DATABASE ステートメントを使用できます。

注意

GRANT および REVOKE を使用して権限を付与および取り消すことができます。

StarRocks はUnified catalogで Hive および Iceberg データベースの作成のみをサポートしています。

Unified catalogに切り替えます、次にそのカタログにデータベースを作成するために次のステートメントを使用します：

CREATE DATABASE <database_name>
[properties ("location" = "<prefix>://<path_to_database>/<database_name.db>")]

location パラメータは、データベースを作成したいファイルパスを指定します。これは HDFS またはクラウドストレージのいずれかにすることができます。

データソースのメタストアとして Hive メタストアを使用する場合、location パラメータはデフォルトで <warehouse_location>/<database_name.db> になり、データベース作成時にそのパラメータを指定しない場合は Hive メタストアによってサポートされます。
データソースのメタストアとして AWS Glue を使用する場合、location パラメータにはデフォルト値がなく、したがってデータベース作成時にそのパラメータを指定する必要があります。

prefix は使用するストレージシステムに基づいて異なります：

ストレージシステム	`Prefix` 値
HDFS	`hdfs`
Google GCS	`gs`
Azure Blob Storage	ストレージアカウントが HTTP 経由でのアクセスを許可する場合、`prefix` は `wasb` です。ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、`prefix` は `wasbs` です。
Azure Data Lake Storage Gen1	`adl`
Azure Data Lake Storage Gen2	ストレージアカウントが HTTP 経由でのアクセスを許可する場合、`prefix` は `abfs` です。ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、`prefix` は `abfss` です。
AWS S3 またはその他の S3 互換ストレージ（例：MinIO）	`s3`

Unified catalogからデータベースを削除する

StarRocks の内部データベースと同様に、Unified catalog内に作成されたデータベースに対して DROP 権限を持っている場合、そのデータベースを削除するために DROP DATABASE ステートメントを使用できます。空のデータベースのみを削除できます。

注意

GRANT および REVOKE を使用して権限を付与および取り消すことができます。

StarRocks はUnified catalogから Hive および Iceberg データベースの削除のみをサポートしています。

Unified catalogからデータベースを削除する際、HDFS クラスターまたはクラウドストレージ上のデータベースのファイルパスはデータベースと共に削除されません。

Unified catalogに切り替えます、次にそのカタログにデータベースを削除するために次のステートメントを使用します：

DROP DATABASE <database_name>

Unified catalogにテーブルを作成する

StarRocks の内部データベースと同様に、Unified catalog内に作成されたデータベースに対して CREATE TABLE 権限を持っている場合、そのデータベースにテーブルを作成するために CREATE TABLE または CREATE TABLE AS SELECT ステートメントを使用できます。

注意

GRANT および REVOKE を使用して権限を付与および取り消すことができます。

StarRocks はUnified catalogで Hive および Iceberg テーブルの作成のみをサポートしています。

Hive Catalog とその中のデータベースに切り替えます。次に、CREATE TABLE を使用して、そのデータベースに Hive または Iceberg テーブルを作成します：

CREATE TABLE <table_name>
(column_definition1[, column_definition2, ...]
ENGINE = {|hive|iceberg}
[partition_desc]

詳細については、Hive テーブルの作成および Iceberg テーブルの作成を参照してください。

次の例では、hive_table という名前の Hive テーブルを作成します。このテーブルは、action、id、および dt の 3 つの列で構成されており、id と dt はパーティション列です。

CREATE TABLE hive_table
(
    action varchar(65533),
    id int,
    dt date
)
ENGINE = hive
PARTITION BY (id,dt);

Unified catalogのテーブルにデータをシンクする

StarRocks の内部テーブルと同様に、Unified catalog内に作成されたテーブルに対して INSERT 権限を持っている場合、その統合カタログテーブルに StarRocks テーブルのデータをシンクするために INSERT ステートメントを使用できます（現在、Parquet 形式の統合カタログテーブルのみがサポートされています）。

注意

GRANT および REVOKE を使用して権限を付与および取り消すことができます。

StarRocks はUnified catalogで Hive および Iceberg テーブルへのデータシンクのみをサポートしています。

Hive Catalog とその中のデータベースに切り替えます。次に、INSERT INTO を使用して、そのデータベース内の Hive または Iceberg テーブルにデータを挿入します：

INSERT {INTO | OVERWRITE} <table_name>
[ (column_name [, ...]) ]
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

-- 指定されたパーティションにデータをシンクしたい場合、次の構文を使用します：
INSERT {INTO | OVERWRITE} <table_name>
PARTITION (par_col1=<value> [, par_col2=<value>...])
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

詳細については、Hive テーブルへのデータシンクおよび Iceberg テーブルへのデータシンクを参照してください。

次の例では、hive_table という名前の Hive テーブルに 3 行のデータを挿入します：

INSERT INTO hive_table
VALUES
    ("buy", 1, "2023-09-01"),
    ("sell", 2, "2023-09-02"),
    ("buy", 3, "2023-09-03");

Unified catalogからテーブルを削除する

StarRocks の内部テーブルと同様に、Unified catalog内に作成されたテーブルに対して DROP 権限を持っている場合、そのテーブルを削除するために DROP TABLE ステートメントを使用できます。

注意

GRANT および REVOKE を使用して権限を付与および取り消すことができます。

StarRocks はUnified catalogから Hive および Iceberg テーブルの削除のみをサポートしています。

Hive Catalog とその中のデータベースに切り替えます。次に、DROP TABLE を使用して、そのデータベース内の Hive または Iceberg テーブルを削除します：

DROP TABLE <table_name>

詳細については、Hive テーブルの削除および Iceberg テーブルの削除を参照してください。

次の例では、hive_table という名前の Hive テーブルを削除します：

DROP TABLE hive_table FORCE

制限事項​

使用上の注意​

統合準備​

AWS IAM​

HDFS​

Kerberos 認証​

Unified catalogの作成​

構文​

パラメータ​

catalog_name​

comment​

type​

MetastoreParams​

Hive メタストア​

AWS Glue​

StorageCredentialParams​

AWS S3​

S3 互換ストレージシステム​

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

Google GCS​

MetadataUpdateParams​

PaimonCatalogParams​

KuduCatalogParams​

例​

HDFS​

AWS S3​

インスタンスプロファイルベースの認証​

アサムドロールベースの認証​

IAM ユーザーベースの認証​

S3 互換ストレージシステム​

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen1​

Azure Data Lake Storage Gen2​

Google GCS​

Unified catalogの表示​

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

Unified catalogを削除する​

Unified catalogからテーブルのスキーマを表示する​

Unified catalogからデータをクエリする​

Hive、Iceberg、Hudi、Delta Lake、または Kudu からデータをロードする​

Unified catalogにデータベースを作成する​

Unified catalogからデータベースを削除する​

Unified catalogにテーブルを作成する​

Unified catalogのテーブルにデータをシンクする​

Unified catalogからテーブルを削除する​

制限事項

使用上の注意

統合準備

AWS IAM

HDFS

Kerberos 認証

Unified catalogの作成

構文

パラメータ

catalog_name

comment

type

MetastoreParams

Hive メタストア

AWS Glue

StorageCredentialParams

AWS S3

S3 互換ストレージシステム

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

Google GCS

MetadataUpdateParams

PaimonCatalogParams

KuduCatalogParams

例

HDFS

AWS S3

インスタンスプロファイルベースの認証

アサムドロールベースの認証

IAM ユーザーベースの認証

S3 互換ストレージシステム

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen1

Azure Data Lake Storage Gen2

Google GCS

Unified catalogの表示

Unified catalogとその中のデータベースに切り替える

Unified catalogを削除する

Unified catalogからテーブルのスキーマを表示する

Unified catalogからデータをクエリする

Hive、Iceberg、Hudi、Delta Lake、または Kudu からデータをロードする

Unified catalogにデータベースを作成する

Unified catalogからデータベースを削除する

Unified catalogにテーブルを作成する

Unified catalogのテーブルにデータをシンクする

Unified catalogからテーブルを削除する