Iceberg catalog

Iceberg catalog は、Apache Iceberg からデータを取り込まずにクエリを実行できる external catalog です。Iceberg クラスターでの SQL ワークロードを成功させるためには、CelerData クラスターが Iceberg クラスターのストレージシステムとメタストアにアクセスできる必要があります。CelerData は以下のストレージシステムとメタストアをサポートしています。

AWS S3 のようなオブジェクトストレージ
Hive metastore (HMS) や AWS Glue のようなメタストア

NOTE

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

使用上の注意

CelerData がサポートする Iceberg のファイル形式は Parquet と ORC です。
- Parquet ファイルは、SNAPPY、LZ4、ZSTD、GZIP、NO_COMPRESSION の圧縮形式をサポートしています。
- ORC ファイルは、ZLIB、SNAPPY、LZO、LZ4、ZSTD、NO_COMPRESSION の圧縮形式をサポートしています。
Iceberg catalogs は、v1 テーブルに加えて、ORC 形式の v2 テーブルと Parquet 形式の v2 テーブルをサポートしています。

準備

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

Hive metastore

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

NOTE

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

CelerData クラスターと Hive metastore を同じ VPC にデプロイする。

CelerData クラスターの VPC と Hive metastore の VPC の間に VPC ピアリング接続を構成する。

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

AWS

Iceberg クラスターが AWS S3 をストレージとして使用している場合、または AWS Glue をメタストアとして使用している場合、適切な認証方法を選択し、IAM ロールまたはユーザーを作成し、指定された IAM ロールまたはユーザーに IAM ポリシーを追加するなど、必要な準備を行って、CelerData クラスターがこれらの AWS リソースにアクセスできるようにしてください。詳細については、Authenticate to AWS resources > Preparations を参照してください。

Microsoft Azure Storage

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

Iceberg catalog の作成

構文

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

パラメータ

catalog_name

Iceberg catalog の名前です。命名規則は以下の通りです。

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

comment

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

type

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

MetastoreParams

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

Hive metastore

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

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

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

Parameter	Required	Description
iceberg.catalog.type	Yes	Iceberg クラスターで使用するメタストアのタイプです。値を `hive` に設定します。
hive.metastore.uris	Yes	Hive metastore の URI です。形式: `thrift://<metastore_IP_address>:<metastore_port>`。 Hive metastore に高可用性 (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 を次のように構成します。
```
"iceberg.catalog.type" = "glue",
"aws.glue.use_instance_profile" = "true",
"aws.glue.region" = "<aws_glue_region>"
```

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

"iceberg.catalog.type" = "glue",
"aws.glue.use_instance_profile" = "true",
"aws.glue.iam_role_arn" = "<iam_role_arn>",
"aws.glue.region" = "<aws_glue_region>"

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

"iceberg.catalog.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
iceberg.catalog.type	Yes	Iceberg クラスターで使用するメタストアのタイプです。値を `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 コンソールでのアクセス制御ポリシーの設定方法については、Authentication parameters for accessing AWS Glue を参照してください。

StorageCredentialParams

CelerData クラスターがオブジェクトストレージと統合する方法に関する一連のパラメータです。

AWS S3

Iceberg クラスターのストレージとして 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 コンソールでのアクセス制御ポリシーの設定方法については、Authentication parameters for accessing AWS S3 を参照してください。

Microsoft Azure Storage

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

Azure Blob Storage

Blob Storage を Iceberg クラスターのストレージとして選択する場合、以下のいずれかのアクションを実行します。

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

"azure.blob.storage_account" = "<blob_storage_account_name>",
"azure.blob.shared_key" = "<blob_storage_account_shared_key>"

以下の表は、パラメータを説明しています。

Parameter	Description
azure.blob.storage_account	Blob ストレージアカウントの名前です。
azure.blob.shared_key	Blob ストレージアカウントの共有キー (アクセスキー) です。

NOTICE

認証に使用するストレージアカウントは、Iceberg クラスターのデータを保存するために使用されるものでなければなりません。

SAS トークン認証方法を使用する場合、StorageCredentialParams を次のように構成します。

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

以下の表は、パラメータを説明しています。

Parameter	Description
azure.blob.storage_account	Blob ストレージアカウントの名前です。
azure.blob.container	Blob ストレージアカウント内のデータを保存する Blob コンテナの名前です。
azure.blob.sas_token	Blob ストレージアカウントにアクセスするために使用される SAS トークンです。

NOTICE

認証に使用するストレージアカウントは、Iceberg クラスターのデータを保存するために使用されるものでなければなりません。

Azure Data Lake Storage Gen2

Data Lake Storage Gen2 を Iceberg クラスターのストレージとして選択する場合、以下のいずれかのアクションを実行します。

マネージドアイデンティティ認証方法を使用する場合、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>"

以下の表は、パラメータを説明しています。

Parameter	Description
azure.adls2.oauth2_use_managed_identity	マネージドアイデンティティ認証方法を有効にするかどうかを指定します。値を `true` に設定します。
azure.adls2.oauth2_tenant_id	ADLS Gen2 ストレージアカウントのテナント ID です。
azure.adls2.oauth2_client_id	デスティネーションクラスターのデータクレデンシャルで参照されるマネージドアイデンティティのクライアント ID です。

NOTICE

認証に使用するストレージアカウントは、Iceberg クラスターのデータを保存するために使用されるものでなければならず、マネージドアイデンティティは CelerData クラスターのデプロイに使用され、ストレージアカウントに対する必要な読み取りおよび書き込み権限 (例: Storage Blob Data Owner) を割り当てられているものでなければなりません。

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

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

以下の表は、パラメータを説明しています。

Parameter	Description
azure.adls2.storage_account	ADLS Gen2 ストレージアカウントの名前です。
azure.adls2.shared_key	ADLS Gen2 ストレージアカウントの共有キー (アクセスキー) です。

NOTICE

認証に使用するストレージアカウントは、Iceberg クラスターのデータを保存するために使用されるものでなければなりません。

サービスプリンシパル認証方法を使用する場合、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>"

以下の表は、パラメータを説明しています。

Parameter	Description
azure.adls2.oauth2_client_id	サービスプリンシパルのアプリケーション (クライアント) ID です。
azure.adls2.oauth2_client_secret	サービスプリンシパルのクライアントシークレットの値です。
azure.adls2.oauth2_client_endpoint	サービスプリンシパルの OAuth 2.0 トークンエンドポイント (v1) です。

NOTICE

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

Azure Data Lake Storage Gen1

Data Lake Storage Gen1 を Iceberg クラスターのストレージとして選択する場合、以下のいずれかのアクションを実行します。

マネージドサービスアイデンティティ認証方法を使用する場合、StorageCredentialParams を次のように構成します。

"azure.adls1.use_managed_service_identity" = "true"

以下の表は、パラメータを説明しています。

Parameter	Description
azure.adls1.use_managed_service_identity	マネージドサービスアイデンティティ認証方法を有効にするかどうかを指定します。値を `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>"

以下の表は、パラメータを説明しています。

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

NOTICE

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

例

以下の例では、使用するメタストアのタイプに応じて、Iceberg クラスターからデータをクエリするための iceberg_catalog_hms または iceberg_catalog_glue という名前の Iceberg catalog を作成します。

AWS S3

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

Iceberg クラスターで Hive metastore を使用する場合、以下のようなコマンドを実行します。

CREATE EXTERNAL CATALOG iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 Iceberg クラスターで AWS Glue を使用する場合、以下のようなコマンドを実行します。

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

アサインされたロールベースの認証

Iceberg クラスターで Hive metastore を使用する場合、以下のようなコマンドを実行します。

CREATE EXTERNAL CATALOG iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 Iceberg クラスターで AWS Glue を使用する場合、以下のようなコマンドを実行します。

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

Iceberg クラスターで Hive metastore を使用する場合、以下のようなコマンドを実行します。

CREATE EXTERNAL CATALOG iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 Iceberg クラスターで AWS Glue を使用する場合、以下のようなコマンドを実行します。

CREATE EXTERNAL CATALOG iceberg_catalog_glue
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 iceberg_catalog_hms
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.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 Gen2

マネージドアイデンティティ認証方法を選択する場合、以下のようなコマンドを実行します。

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

Azure Data Lake Storage Gen1

マネージドサービスアイデンティティ認証方法を選択する場合、以下のようなコマンドを実行します。

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

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

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

Iceberg catalogs の表示

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

SHOW CATALOGS;

また、external catalog の作成ステートメントをクエリするには、SHOW CREATE CATALOG を使用できます。以下の例では、iceberg_catalog_glue という名前の Iceberg catalog の作成ステートメントをクエリします。

SHOW CREATE CATALOG iceberg_catalog_glue;

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

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

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

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

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

Iceberg catalog の削除

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

以下の例では、iceberg_catalog_glue という名前の Iceberg catalog を削除します。

DROP Catalog iceberg_catalog_glue;

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

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

スキーマを表示

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

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

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

Iceberg テーブルをクエリする

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

Iceberg データベースを作成する

CelerData の internal catalog と同様に、Iceberg catalog に対して CREATE DATABASE 権限を持っている場合、CREATE DATABASE ステートメントを使用して、その Iceberg catalog にデータベースを作成できます。

NOTE

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

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

location パラメータを使用して、データベースを作成するファイルパスを指定できます。 location パラメータを指定しない場合、CelerData は Iceberg catalog のデフォルトのファイルパスにデータベースを作成します。

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

Storage system	`Prefix` value
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`

Iceberg データベースを削除する

CelerData の internal databases と同様に、Iceberg データベースに対して DROP 権限を持っている場合、DROP DATABASE ステートメントを使用して、その Iceberg データベースを削除できます。空のデータベースのみを削除できます。

NOTE

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

Iceberg データベースを削除すると、そのデータベースのファイルパスは削除されません。

Iceberg catalog に切り替えるし、その catalog 内の Iceberg データベースを削除するには、次のステートメントを使用します。

DROP DATABASE <database_name>

Iceberg テーブルを作成する

CelerData の internal databases と同様に、Iceberg データベースに対して CREATE TABLE 権限を持っている場合、CREATE TABLE または CREATE TABLE AS SELECT (CTAS) ステートメントを使用して、その Iceberg データベースにテーブルを作成できます。

NOTE

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

Iceberg catalog とその中のデータベースに切り替えるし、そのデータベースに Iceberg テーブルを作成するには、次の構文を使用します。

構文

CREATE TABLE [IF NOT EXISTS] [database.]table_name
(column_definition1[, column_definition2, ...
partition_column_definition1,partition_column_definition2...])
[partition_desc]
[PROPERTIES ("key" = "value", ...)]
[AS SELECT query]

パラメータ

column_definition

column_definition の構文は次のとおりです。

col_name col_type [COMMENT 'comment']

以下の表は、パラメータを説明しています。

Parameter	Description
col_name	カラムの名前です。
col_type	カラムのデータ型です。サポートされているデータ型は、TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、DATE、DATETIME、CHAR、VARCHAR[(length)]、ARRAY、MAP、および STRUCT です。LARGEINT、HLL、および BITMAP データ型はサポートされていません。

NOTICE

すべての非パーティションカラムは、デフォルト値として NULL を使用する必要があります。つまり、テーブル作成ステートメントで各非パーティションカラムに対して DEFAULT "NULL" を指定する必要があります。さらに、パーティションカラムは非パーティションカラムの後に定義され、デフォルト値として NULL を使用することはできません。

partition_desc

partition_desc の構文は次のとおりです。

PARTITION BY (par_col1[, par_col2...])

現在、CelerData は identity transforms のみをサポートしており、CelerData は各ユニークなパーティション値に対してパーティションを作成します。

NOTICE

パーティションカラムは非パーティションカラムの後に定義される必要があります。パーティションカラムは、FLOAT、DOUBLE、DECIMAL、および DATETIME を除くすべてのデータ型をサポートし、デフォルト値として NULL を使用することはできません。

properties

properties で "key" = "value" 形式でテーブル属性を指定できます。Iceberg table attributes を参照してください。

以下の表は、いくつかの主要なプロパティを説明しています。

Property	Description
location	Iceberg テーブルを作成するファイルパスです。HMS をメタストアとして使用する場合、`location` パラメータを指定する必要はありません。StarRocks は現在の Iceberg catalog のデフォルトのファイルパスにテーブルを作成します。AWS Glue をメタストアとして使用する場合: テーブルを作成するデータベースに対して `location` パラメータを指定している場合、テーブルに対して `location` パラメータを指定する必要はありません。この場合、テーブルは所属するデータベースのファイルパスにデフォルトで設定されます。テーブルを作成するデータベースに対して `location` を指定していない場合、テーブルに対して `location` パラメータを指定する必要があります。
file_format	Iceberg テーブルのファイル形式です。Parquet 形式のみがサポートされています。デフォルト値: `parquet`。
compression_codec	Iceberg テーブルに使用される圧縮アルゴリズムです。サポートされている圧縮アルゴリズムは、SNAPPY、GZIP、ZSTD、および LZ4 です。デフォルト値: `gzip`。

例

unpartition_tbl という名前の非パーティションテーブルを作成します。このテーブルは、以下のように id と score の 2 つのカラムで構成されています。
```
CREATE TABLE unpartition_tbl
(
    id int,
    score double
);
```
partition_tbl_1 という名前のパーティションテーブルを作成します。このテーブルは、以下のように action、id、および dt の 3 つのカラムで構成されており、id と dt がパーティションカラムとして定義されています。
```
CREATE TABLE partition_tbl_1
(
    action varchar(20),
    id int,
    dt date
)
PARTITION BY (id,dt);
```
既存のテーブル partition_tbl_1 をクエリし、そのクエリ結果に基づいて partition_tbl_2 という名前のパーティションテーブルを作成します。partition_tbl_2 では、id と dt がパーティションカラムとして定義されています。
```
CREATE TABLE partition_tbl_2
PARTITION BY (k1, k2)
AS SELECT * from partition_tbl_1;
```

Iceberg テーブルにデータをシンクする

CelerData の internal tables と同様に、Iceberg テーブルに対して INSERT 権限を持っている場合、INSERT ステートメントを使用して、CelerData テーブルのデータをその Iceberg テーブルにシンクできます (現在、Parquet 形式の Iceberg テーブルのみがサポートされています)。

NOTE

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

Iceberg catalog とその中のデータベースに切り替えるし、そのデータベース内の Parquet 形式の Iceberg テーブルに StarRocks テーブルのデータをシンクするには、次の構文を使用します。

構文

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 }

NOTICE

パーティションカラムは NULL 値を許可しません。したがって、Iceberg テーブルのパーティションカラムに空の値がロードされないようにする必要があります。

パラメータ

Parameter	Description
INTO	CelerData テーブルのデータを Iceberg テーブルに追加します。
OVERWRITE	Iceberg テーブルの既存のデータを CelerData テーブルのデータで上書きします。
column_name	データをロードしたい宛先カラムの名前です。1 つ以上のカラムを指定できます。複数のカラムを指定する場合は、カンマ (`,`) で区切ります。実際に Iceberg テーブルに存在するカラムのみを指定できます。指定した宛先カラムは、Iceberg テーブルのパーティションカラムを含む必要があります。指定した宛先カラムは、CelerData テーブルのカラムと順番に 1 対 1 でマッピングされます。宛先カラム名が何であっても関係ありません。宛先カラムが指定されていない場合、データは Iceberg テーブルのすべてのカラムにロードされます。CelerData テーブルの非パーティションカラムが Iceberg テーブルのカラムにマッピングできない場合、CelerData は Iceberg テーブルカラムにデフォルト値 `NULL` を書き込みます。INSERT ステートメントにクエリステートメントが含まれており、その戻り値のカラムタイプが宛先カラムのデータ型と異なる場合、CelerData は不一致のカラムに対して暗黙の変換を行います。変換が失敗した場合、構文解析エラーが返されます。
expression	宛先カラムに値を割り当てる式です。
DEFAULT	宛先カラムにデフォルト値を割り当てます。
query	Iceberg テーブルにロードされる結果を持つクエリステートメントです。CelerData がサポートする任意の SQL ステートメントを使用できます。
PARTITION	データをロードしたいパーティションです。このプロパティで Iceberg テーブルのすべてのパーティションカラムを指定する必要があります。このプロパティで指定するパーティションカラムは、テーブル作成ステートメントで定義したパーティションカラムと異なる順序で指定できます。このプロパティを指定する場合、`column_name` プロパティを指定することはできません。

例

partition_tbl_1 テーブルに 3 行のデータを挿入します。

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

簡単な計算を含む SELECT クエリの結果を partition_tbl_1 テーブルに挿入します。
```
INSERT INTO partition_tbl_1 (id, action, dt) SELECT 1+1, 'buy', '2023-09-03';
```
partition_tbl_1 テーブルからデータを読み取る SELECT クエリの結果を同じテーブルに挿入します。
```
INSERT INTO partition_tbl_1 SELECT 'buy', 1, date_add(dt, INTERVAL 2 DAY)
FROM partition_tbl_1
WHERE id=1;
```
partition_tbl_2 テーブルの dt='2023-09-01' および id=1 の条件を満たすパーティションに SELECT クエリの結果を挿入します。
```
INSERT INTO partition_tbl_2 SELECT 'order', 1, '2023-09-01';
```
または
```
INSERT INTO partition_tbl_2 partition(dt='2023-09-01',id=1) SELECT 'order';
```
partition_tbl_1 テーブルの dt='2023-09-01' および id=1 の条件を満たすパーティションのすべての action カラム値を close で上書きします。
```
INSERT OVERWRITE partition_tbl_1 SELECT 'close', 1, '2023-09-01';
```
または
```
INSERT OVERWRITE partition_tbl_1 partition(dt='2023-09-01',id=1) SELECT 'close';
```

Iceberg テーブルを削除する

CelerData の internal tables と同様に、Iceberg テーブルに対して DROP 権限を持っている場合、DROP TABLE ステートメントを使用して、その Iceberg テーブルを削除できます。

NOTE

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

Iceberg テーブルを削除すると、そのテーブルのファイルパスとデータは削除されません。

Iceberg テーブルを強制的に削除する場合 (つまり、DROP TABLE ステートメントで FORCE キーワードを指定した場合)、そのテーブルのデータは削除されますが、テーブルのファイルパスは保持されます。

Iceberg catalog とその中のデータベースに切り替えるし、そのデータベース内の Iceberg テーブルを削除するには、次のステートメントを使用します。

DROP TABLE <table_name> [FORCE];

使用上の注意​

準備​

Hive metastore​

AWS​

Microsoft Azure Storage​

Iceberg catalog の作成​

構文​

パラメータ​

catalog_name​

comment​

type​

MetastoreParams​

Hive metastore​

AWS Glue​

StorageCredentialParams​

AWS S3​

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

例​

AWS S3​

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

アサインされたロールベースの認証​

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

Microsoft Azure Storage​

Azure Blob Storage​

Azure Data Lake Storage Gen2​

Azure Data Lake Storage Gen1​

Iceberg catalogs の表示​

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

Iceberg catalog の削除​

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

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

Iceberg データベースを作成する​

Iceberg データベースを削除する​

Iceberg テーブルを作成する​

構文​

パラメータ​

column_definition​

partition_desc​

properties​

例​

Iceberg テーブルにデータをシンクする​

構文​

パラメータ​

例​

Iceberg テーブルを削除する​

使用上の注意

準備

Hive metastore

AWS

Microsoft Azure Storage

Iceberg catalog の作成

構文

パラメータ

catalog_name

comment

type

MetastoreParams

Hive metastore

AWS Glue

StorageCredentialParams

AWS S3

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

例

AWS S3

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

アサインされたロールベースの認証

IAM ユーザーベースの認証

Microsoft Azure Storage

Azure Blob Storage

Azure Data Lake Storage Gen2

Azure Data Lake Storage Gen1

Iceberg catalogs の表示

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

Iceberg catalog の削除

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

Iceberg テーブルをクエリする

Iceberg データベースを作成する

Iceberg データベースを削除する

Iceberg テーブルを作成する

構文

パラメータ

column_definition

partition_desc

properties

例

Iceberg テーブルにデータをシンクする

構文

パラメータ

例

Iceberg テーブルを削除する