メインコンテンツまでスキップ
バージョン: Latest-4.0

Iceberg catalog

ヒント

この例では、StarRocks Basics クイックスタートで紹介されている Local Climatological Data (LCD) データセットを使用しています。データをロードして、自分で例を試すことができます。

Iceberg catalog は、StarRocks が v2.4 以降でサポートする外部 catalog の一種です。Iceberg catalog を使用すると、以下のことが可能です。

  • Iceberg に保存されたデータを直接クエリし、手動でテーブルを作成する必要がありません。
  • Iceberg に保存されたデータを処理し、StarRocks にデータをロードするために INSERT INTO または非同期マテリアライズドビュー（v2.5 以降でサポート）を使用します。
  • StarRocks 上で操作を行い、Iceberg データベースやテーブルを作成または削除したり、StarRocks テーブルから Parquet 形式の Iceberg テーブルにデータをシンクするために INSERT INTO を使用します（この機能は v3.1 以降でサポート）。

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

  • 分散ファイルシステム（HDFS）または AWS S3、Microsoft Azure Storage、Google GCS、または他の S3 互換ストレージシステム（例: MinIO）

  • メタストアとして Hive metastore、AWS Glue、または Tabular

注記
  • ストレージとして AWS S3 を選択した場合、メタストアとして HMS または AWS Glue を使用できます。他のストレージシステムを選択した場合、メタストアとして HMS のみを使用できます。
  • メタストアとして Tabular を選択した場合、Iceberg REST catalog を使用する必要があります。

使用上の注意​

StarRocks を使用して Iceberg からデータをクエリする際には、以下の点に注意してください。

ファイル形式圧縮形式Iceberg テーブルバージョン
ParquetSNAPPY, LZ4, ZSTD, GZIP, NO_COMPRESSION
  • v1 テーブル: サポートされています。
  • v2 テーブル: StarRocks v3.1 以降でサポートされており、これらの v2 テーブルに対するクエリは位置削除をサポートします。v3.1.10、v3.2.5、v3.3 およびそれ以降のバージョンでは、v2 テーブルに対するクエリは等価削除もサポートします。
ORCZLIB, SNAPPY, LZO, LZ4, ZSTD, NO_COMPRESSION
  • v1 テーブル: サポートされています。
  • v2 テーブル: StarRocks v3.0 以降でサポートされており、これらの v2 テーブルに対するクエリは位置削除をサポートします。v3.1.8、v3.2.3、v3.3 およびそれ以降のバージョンでは、v2 テーブルに対するクエリは等価削除もサポートします。

統合準備​

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

ストレージ​

ストレージタイプに一致するタブを選択してください。

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

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

  • インスタンスプロファイル
  • 想定ロール
  • IAM ユーザー

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

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

Iceberg catalog の作成​

構文​

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

パラメーター​

catalog_name​

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

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

comment​

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

type​

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

SecurityParams​

StarRock sがカタログへのデータアクセスを管理する方法に関するパラメータ。

Iceberg REST カタログのデータアクセス管理の詳細な手順については、Iceberg REST カタログのセキュリティ設定を参照してください。

catalog.access.control​

データアクセス制御ポリシー。有効な値：

  • native (デフォルト): StarRocks 組み込みのデータアクセス制御システムを使用します。
  • allowall: すべてのデータアクセスチェックをカタログ自体に委譲します。
  • ranger: データアクセスチェックを Apache Ranger に委譲します。

MetastoreParams​

StarRocks がデータソースのメタストアと統合する方法に関する一連のパラメーターです。メタストアタイプに一致するタブを選択してください。

Hive metastore​

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

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

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

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

  • iceberg.catalog.type

    • 必須: はい
    • 説明: Iceberg クラスターで使用するメタストアのタイプ。値を hive に設定します。

  • hive.metastore.uris

    • 必須: はい
    • 説明: 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>"。

StorageCredentialParams​

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

次の点に注意してください。

  • ストレージとして HDFS を使用する場合、StorageCredentialParams を構成する必要はなく、このセクションをスキップできます。ストレージとして AWS S3、他の S3 互換ストレージシステム、Microsoft Azure Storage、または Google GCS を使用する場合、StorageCredentialParams を構成する必要があります。

  • メタストアとして Tabular を使用する場合、StorageCredentialParams を構成する必要はなく、このセクションをスキップできます。メタストアとして HMS または AWS Glue を使用する場合、StorageCredentialParams を構成する必要があります。

ストレージタイプに一致するタブを選択してください。

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>"

  • REST カタログで Vended Credential（v4.0以降でサポート）を選択するには、StorageCredentialParams を次のように構成します。

    "aws.s3.region" = "<aws_s3_region>"

AWS S3 用の 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 へのアクセス認証パラメーター を参照してください。

MetadataRelatedParams​

StarRocks における Iceberg メタデータのキャッシュに関するパラメーターのセットです。このパラメーターセットはオプションです。

v3.3.3 以降、StarRocks は 定期的なメタデータリフレッシュ戦略 をサポートしています。ほとんどの場合、以下のパラメーターを無視し、そのポリシーパラメーターを調整する必要はありません。これらのパラメーターのデフォルト値は、すぐに使用できるパフォーマンスを提供します。システム変数 plan_mode を使用して Iceberg メタデータパースモードを調整できます。

パラメーターデフォルト説明
enable_iceberg_metadata_cachetrueIceberg 関連のメタデータ（Table Cache、Partition Name Cache、Manifest 内の Data File Cache および Delete Data File Cache を含む）をキャッシュするかどうか。
iceberg_manifest_cache_with_column_statisticsfalse列の統計をキャッシュするかどうか。
refresh_iceberg_manifest_min_length2 * 1024 * 1024Data File Cache のリフレッシュをトリガーする最小の Manifest ファイル長。
iceberg_data_file_cache_memory_usage_ratio0.1Data File Manifest キャッシュの最大メモリ使用率。v3.5.6 以降でサポートされています。
iceberg_delete_file_cache_memory_usage_ratio0.1Delete File Manifest キャッシュの最大メモリ使用率。v3.5.6 以降でサポートされています。
iceberg_table_cache_refresh_interval_sec60Iceberg テーブルキャッシュの非同期更新がトリガーされる間隔（秒単位）。v3.5.7 以降でサポートされています。

v3.4 以降、StarRocks は、以下のパラメーターを設定することで、Iceberg メタデータを読み取ることで Iceberg テーブルの統計情報を取得できます。これにより、Iceberg テーブルの統計情報の収集を積極的にトリガーする必要はありません。

パラメーターデフォルト説明
enable_get_stats_from_external_metadatafalseIceberg メタデータから統計情報を取得するかどうか。この項目を true に設定すると、セッション変数 enable_get_stats_from_external_metadata を通じて、収集する統計情報の種類をさらに制御できます。

例​

以下の例は、使用するメタストアのタイプに応じて、Iceberg クラスターからデータをクエリするための Iceberg catalog iceberg_catalog_hms または iceberg_catalog_glue を作成します。ストレージタイプに一致するタブを選択してください。

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"
    );
Vended Credential を選択した場合​

REST カタログで Vended Credential を選択する場合、次のようなコマンドを実行します。

CREATE EXTERNAL CATALOG polaris_s3
PROPERTIES
(
    "type" = "iceberg",
    "iceberg.catalog.uri" = "http://xxx:xxx/api/catalog",
    "iceberg.catalog.type" = "rest",
    "iceberg.catalog.rest.nested-namespace-enabled"="true",
    "iceberg.catalog.security" = "oauth2",
    "iceberg.catalog.oauth2.credential" = "xxxxx:xxxx",
    "iceberg.catalog.oauth2.scope"='PRINCIPAL_ROLE:ALL',
    "iceberg.catalog.warehouse" = "iceberg_catalog",
    "aws.s3.region" = "us-west-2"
);

カタログの使用​

Iceberg catalog の表示​

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

SHOW CATALOGS;

外部 catalog の作成ステートメントをクエリするには、 SHOW CREATE CATALOG を使用することもできます。次の例は、Iceberg catalog iceberg_catalog_glue の作成ステートメントをクエリします。

SHOW CREATE CATALOG iceberg_catalog_glue;

Iceberg Catalog とそのデータベースへの切り替え​

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

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

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

  • Iceberg catalog とそのデータベースに直接切り替えるには USE を使用します。

    USE <catalog_name>.<db_name>

Iceberg catalog の削除​

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

次の例は、Iceberg catalog iceberg_catalog_glue を削除します。

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 テーブルをクエリ​

  1. Iceberg クラスター内のデータベースを表示するには、 SHOW DATABASES を使用します。

    SHOW DATABASES FROM <catalog_name>

  2. Iceberg catalog とそのデータベースに切り替えます。

  3. 指定されたデータベース内の宛先テーブルをクエリするには、 SELECT を使用します。

    SELECT count(*) FROM <table_name> LIMIT 10

Iceberg データベースの作成​

StarRocks の内部 catalog と同様に、Iceberg catalog に対して CREATE DATABASE 権限を持っている場合、 CREATE DATABASE ステートメントを使用して、その Iceberg catalog にデータベースを作成できます。この機能は v3.1 以降でサポートされています。

ヒント

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

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

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

location パラメーターを使用して、データベースを作成するファイルパスを指定できます。HDFS とクラウドストレージの両方がサポートされています。location パラメーターを指定しない場合、StarRocks は Iceberg catalog のデフォルトのファイルパスにデータベースを作成します。

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

HDFS​

Prefix 値: hdfs

Google GCS​

Prefix 値: gs

Azure Blob Storage​

Prefix 値:

  • ストレージアカウントが HTTP 経由でのアクセスを許可する場合、prefix は wasb です。
  • ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、prefix は wasbs です。

Azure Data Lake Storage Gen1​

Prefix 値: adl

Azure Data Lake Storage Gen2​

Prefix 値:

  • ストレージアカウントが HTTP 経由でのアクセスを許可する場合、prefix は abfs です。
  • ストレージアカウントが HTTPS 経由でのアクセスを許可する場合、prefix は abfss です。

AWS S3 または他の S3 互換ストレージ（例: MinIO）​

Prefix 値: s3

Iceberg データベースの削除​

StarRocks の内部データベースと同様に、Iceberg データベースに対して DROP 権限を持っている場合、 DROP DATABASE ステートメントを使用して、その Iceberg データベースを削除できます。この機能は v3.1 以降でサポートされています。空のデータベースのみを削除できます。

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

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

DROP DATABASE <database_name>;

Iceberg テーブルの作成​

StarRocks の内部データベースと同様に、Iceberg データベースに対して CREATE TABLE 権限を持っている場合、 CREATE TABLE または [CREATE TABLE AS SELECT ../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.mdELECT.md) ステートメントを使用して、その Iceberg データベースにテーブルを作成できます。この機能は v3.1 以降でサポートされています。

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

構文​

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

パラメーター​

column_definition​

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

col_name col_type [COMMENT 'comment']
注記

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

partition_desc​

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

PARTITION BY (partition_expr[, partition_expr...])

各 partition_expr は以下の形式のいずれかです。

column_name
| transform_expr(column_name)
| transform_expr(column_name, parameter)

現在、StarRocks は Apache Iceberg 仕様で定義されたパーティション変換式 transform expr をサポートしています。これにより、StarRocks は変換された列値に基づいて隠しパーティション (Hidden Partition) を持つ Iceberg テーブルを作成できます。

注記

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

ORDER BY​

v4.0 以降、StarRocks は ORDER BY 句を介して Iceberg テーブルのソートキーを指定する機能をサポートしています。これにより、指定されたソートキーに基づいて同一データファイル内のデータを並べ替えることが可能です。

ORDER BY 句には複数のソートキーを含めることができ、以下の形式で指定します：

ORDER BY (column_name [sort_direction] [nulls_order], ...)
  • column_name: ソートキーとして使用する列の名前。テーブルスキーマに存在する列でなければなりません。現在、Transform 式はサポートされていません。
  • sort_direction: ソート方向。有効な値: ASC (デフォルト) および DESC。
  • nulls_order: NULL 値の順序。有効な値: NULLS FIRST (ASC 指定時のデフォルト) および NULLS LAST (DESC 指定時のデフォルト)。

sort_direction および nulls_order はオプションです。例えば、以下の各々は有効な sort_desc です：

  • column_name
  • column_name ASC
  • column_name DESC NULLS FIRST
PROPERTIES​

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

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

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。このプロパティは v3.2.3 で非推奨となり、それ以降のバージョンでは Iceberg テーブルにデータをシンクするために使用される圧縮アルゴリズムはセッション変数 connector_sink_compression_codec によって一元的に制御されます。

例​

  1. unpartition_tbl という名前の非パーティションテーブルを作成します。このテーブルは id と score の 2 つの列で構成されています。

    CREATE TABLE unpartition_tbl
    (
        id int,
        score double
    );

  2. 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);

  3. 既存のテーブル partition_tbl_1 をクエリし、そのクエリ結果に基づいて partition_tbl_2 という名前のパーティションテーブルを作成します。partition_tbl_2 では、id と dt がパーティション列として定義されています。

    CREATE TABLE partition_tbl_2
    PARTITION BY (id, dt)
    AS SELECT * from employee;

  4. 隠されたパーティションを持つ partition_tbl_3 という名前のテーブルを作成します。このテーブルには action、id、dt の三つの列が含まれています。そのうち、id と dt はパーティションキーとして使用されますが、パーティションは変換式によって定義されているため、これらのパーティションは隠されています。

    CREATE TABLE partition_tbl_3 (
      action VARCHAR(20),
      id INT,
      dt DATE
    )
    PARTITION BY bucket(id, 10), year(dt);

パーティション Spec の進化（ADD/DROP PARTITION COLUMN）​

StarRocks は ALTER TABLE ... ADD|DROP PARTITION COLUMN を使用して Iceberg テーブルのパーティション Spec（変換式を含む）を進化させることをサポートします。

構文​

ALTER TABLE [catalog.][database.]table_name
ADD PARTITION COLUMN partition_expr [, partition_expr ...];

ALTER TABLE [catalog.][database.]table_name
DROP PARTITION COLUMN partition_expr [, partition_expr ...];

partition_expr は列名（Identity 変換）または次の変換式のいずれかを指定できます: year、month、day、hour、truncate、bucket。

例​

ALTER TABLE test_part_evo
ADD PARTITION COLUMN dt, truncate(value, 10), bucket(id, 10);

ALTER TABLE test_part_evo
DROP PARTITION COLUMN dt;

ALTER TABLE test_part_evo
ADD PARTITION COLUMN month(dt);

Iceberg テーブルへのデータシンク​

StarRocks の内部テーブルと同様に、Iceberg テーブルに対して INSERT 権限を持っている場合、 INSERT ステートメントを使用して、StarRocks テーブルのデータをその Iceberg テーブルにシンクできます（現在、Parquet 形式の Iceberg テーブルのみがサポートされています）。この機能は v3.1 以降でサポートされています。

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 }
注記

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

パラメーター​

INTO​

StarRocks テーブルのデータを Iceberg テーブルに追加します。

OVERWRITE​

StarRocks テーブルのデータで Iceberg テーブルの既存のデータを上書きします。

column_name​

データをロードしたい宛先列の名前。1 つ以上の列を指定できます。複数の列を指定する場合、カンマ (,) で区切ります。Iceberg テーブルに実際に存在する列のみを指定できます。また、指定した宛先列には Iceberg テーブルのパーティション列を含める必要があります。指定した宛先列は、StarRocks テーブルの列と順番に 1 対 1 でマッピングされます。宛先列名が何であっても関係ありません。宛先列が指定されていない場合、データは Iceberg テーブルのすべての列にロードされます。StarRocks テーブルの非パーティション列が Iceberg テーブルの任意の列にマッピングできない場合、StarRocks は Iceberg テーブル列にデフォルト値 NULL を書き込みます。INSERT ステートメントに含まれるクエリステートメントの戻り列タイプが宛先列のデータタイプと異なる場合、StarRocks は不一致の列に対して暗黙の変換を行います。変換が失敗した場合、構文解析エラーが返されます。

expression​

宛先列に値を割り当てる式。

DEFAULT​

宛先列にデフォルト値を割り当てます。

query​

Iceberg テーブルにロードされるクエリステートメントの結果。StarRocks がサポートする任意の SQL ステートメントである可能性があります。

PARTITION​

データをロードしたいパーティション。Iceberg テーブルのすべてのパーティション列をこのプロパティで指定する必要があります。このプロパティで指定するパーティション列は、テーブル作成ステートメントで定義したパーティション列と異なる順序であってもかまいません。このプロパティを指定する場合、column_name プロパティを指定することはできません。

例​

  1. 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");

  2. 簡単な計算を含む SELECT クエリの結果を partition_tbl_1 テーブルに挿入します。

    INSERT INTO partition_tbl_1 (id, action, dt) SELECT 1+1, 'buy', '2023-09-03';

  3. 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;

  4. 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';

  5. 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 テーブルの削除​

StarRocks の内部テーブルと同様に、Iceberg テーブルに対して DROP 権限を持っている場合、 DROP TABLE ステートメントを使用して、その Iceberg テーブルを削除できます。この機能は v3.1 以降でサポートされています。

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

Iceberg テーブルを強制的に削除する場合（つまり、DROP TABLE ステートメントで FORCE キーワードを指定した場合）、HDFS クラスターまたはクラウドストレージ上のテーブルのデータはテーブルと共に削除されますが、テーブルのファイルパスは保持されます。

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

DROP TABLE <table_name> [FORCE];

Iceberg ビューの作成​

StarRocks で Iceberg ビューを定義したり 、 既存の Iceberg ビューに StarRocks 方言を追加することがで き ます。このような Iceberg ビューに対するクエリは、これらのビューの StarRocks 方言の解析をサポートします。この機能は v3.5 以降でサポートされています。

CREATE VIEW [IF NOT EXISTS]
[<catalog>.<database>.]<view_name>
(
    <column_name>[ COMMENT 'column comment']
    [, <column_name>[ COMMENT 'column comment'], ...]
)
[COMMENT 'view comment']
[PROPERTIES ("key" = "value", ...)]
AS <query_statement>

例​

Iceberg テーブル iceberg_table に基づいて Iceberg ビュー iceberg_view1 を作成する。

CREATE VIEW IF NOT EXISTS iceberg.iceberg_db.iceberg_view1 AS
SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;

v4.0.3以降、PROPERTIES 内でビュー属性を "key" = "value" 形式で指定できます。

CREATE VIEW IF NOT EXISTS iceberg.iceberg_db.iceberg_view1
PROPERTIES (
  "key1" = "value1",
  "key2" = "value2"
)
AS
SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;

既存の Iceberg ビューに StarRocks 方言を追加または変更する​

Iceberg ビューが Apache Spark などの他のシステムから作成されており、StarRocks からこれらのビューにクエリを実行したい場合、これらのビューに StarRocks 方言を追加できます。この機能は v3.5 以降でサポートされています。

注記
  • ビューの両方の方言の本質的な意味が同一であることを保証する必要があります。StarRocks や他のシステムでは、異なる定義間の一貫性は保証されません。
  • 各 Iceberg ビューに対して定義できる StarRocks 方言は 1 つだけです。方言の定義は MODIFY 句を使用して変更できます。
ALTER VIEW
[<catalog>.<database>.]<view_name>
(
    <column_name>
    [, <column_name>]
)
{ ADD | MODIFY } DIALECT
<query_statement>

例​

  1. 既存の Iceberg ビュー iceberg_view2 に StarRocks 方言を追加する。
ALTER VIEW iceberg.iceberg_db.iceberg_view2 ADD DIALECT SELECT k1, k2 FROM iceberg.iceberg_db.iceberg_table;
  1. 既存の Iceberg ビュー iceberg_view2 の StarRocks 方言を変更する。
ALTER VIEW iceberg.iceberg_db.iceberg_view2 MODIFY DIALECT SELECT k1, k2, k3 FROM iceberg.iceberg_db.iceberg_table;

手動コンパクション​

v4.0 以降、StarRocks は Iceberg テーブルに対する手動コンパクションをサポートしています。

Iceberg テーブルにデータがロードされるたびに、新しいデータファイルとメタデータファイルが生成されます。時間の経過とともに過剰なデータファイルが蓄積されると、クエリプランの生成が大幅に遅延し、パフォーマンスに影響を及ぼす可能性があります。

この場合、テーブルまたはパーティションに対して手動コンパクションを実行し、小さなデータファイルをマージすることでパフォーマンスを改善する必要があります。

構文​

ALTER TABLE [catalog.][database.]table_name 
EXECUTE rewrite_data_files
("key"=value [,"key"=value, ...]) 
[WHERE <predicate>]

パラメータ​

rewrite_data_files プロパティ​

手動コンパクションの動作を指定する "key"=value ペア。キーは二重引用符で囲む必要があることに注意してください。

min_file_size_bytes​
  • 説明: 小規模データファイルの上限値。この値より小さいサイズのデータファイルは、コンパクション時にマージされます。
  • 単位: Byte
  • タイプ: Int
  • デフォルト: 268,435,456 (256 MB)
batch_size​
  • 説明: 各バッチで処理可能なデータの最大サイズ。
  • 単位: Byte
  • タイプ: Int
  • デフォルト: 10,737,418,240 (10 GB)
rewrite_all​
  • 説明: 特定の要件を持つデータファイルをフィルタリングするパラメータを無視し、コンパクション中にすべてのデータファイルを書き換えるかどうか。
  • 単位: -
  • タイプ: Boolean
  • デフォルト: false
WHERE 句​
  • 説明: コンパクションに含めるパーティションを指定するために使用されるフィルタ述語。

例​

以下の例は、Iceberg テーブル t1 内の特定のパーティションに対して手動コンパクションを実行します。パーティションは part_col = 'p1' 句で指定されます。これらのパーティションでは、134,217,728 Byte（128 MB）未満のデータファイルがコンパクション中にマージされます。

ALTER TABLE t1 EXECUTE rewrite_data_files("min_file_size_bytes"= 134217728) WHERE part_col = 'p1';

メタデータキャッシュの構成​

Iceberg クラスターのメタデータファイルは、AWS S3 や HDFS などのリモートストレージに保存されている場合があります。デフォルトでは、StarRocks はメモリ内に Iceberg メタデータをキャッシュします。クエリを高速化するために、StarRocks はメモリとディスクの両方にメタデータをキャッシュできる 2 レベルのメタデータキャッシングメカニズムを採用しています。初期クエリごとに、StarRocks はその計算結果をキャッシュします。以前のクエリと意味的に等価な後続のクエリが発行された場合、StarRocks は最初にそのキャッシュから要求されたメタデータを取得しようとし、キャッシュでメタデータがヒットしない場合にのみリモートストレージからメタデータを取得します。

StarRocks は、データをキャッシュおよび削除するために最も最近使用されたものを優先する（LRU）アルゴリズムを使用します。基本的なルールは次のとおりです。

  • StarRocks は最初にメモリから要求されたメタデータを取得しようとします。メモリでメタデータがヒットしない場合、StarRocks はディスクからメタデータを取得しようとします。StarRocks がディスクから取得したメタデータはメモリにロードされます。ディスクでもメタデータがヒットしない場合、StarRocks はリモートストレージからメタデータを取得し、取得したメタデータをメモリにキャッシュします。
  • StarRocks はメモリから削除されたメタデータをディスクに書き込みますが、ディスクから削除されたメタデータは直接破棄します。

v3.3.3 以降、StarRocks は 定期的なメタデータリフレッシュ戦略 をサポートしています。システム変数 plan_mode を使用して Iceberg メタデータキャッシュプランを調整できます。

Iceberg メタデータキャッシュに関する FE の設定​

enable_iceberg_metadata_disk_cache​
  • 単位: N/A
  • デフォルト値: false
  • 説明: ディスクキャッシュを有効にするかどうかを指定します。
iceberg_metadata_cache_disk_path​
  • 単位: N/A
  • デフォルト値: StarRocksFE.STARROCKS_HOME_DIR + "/caches/iceberg"
  • 説明: ディスク上のキャッシュされたメタデータファイルの保存パス。
iceberg_metadata_disk_cache_capacity​
  • 単位: バイト
  • デフォルト値: 2147483648、2 GB に相当
  • 説明: ディスク上で許可されるキャッシュされたメタデータの最大サイズ。
iceberg_metadata_memory_cache_capacity​
  • 単位: バイト
  • デフォルト値: 536870912、512 MB に相当
  • 説明: メモリ内で許可されるキャッシュされたメタデータの最大サイズ。
iceberg_metadata_memory_cache_expiration_seconds​
  • 単位: 秒
  • デフォルト値: 86500
  • 説明: メモリ内のキャッシュエントリが最後にアクセスされてから期限切れになるまでの時間。
iceberg_metadata_disk_cache_expiration_seconds​
  • 単位: 秒
  • デフォルト値: 604800、1 週間に相当
  • 説明: ディスク上のキャッシュエントリが最後にアクセスされてから期限切れになるまでの時間。
iceberg_metadata_cache_max_entry_size​
  • 単位: バイト
  • デフォルト値: 8388608、8 MB に相当
  • 説明: キャッシュできるファイルの最大サイズ。このパラメーターの値を超えるサイズのファイルはキャッシュできません。クエリがこれらのファイルを要求する場合、StarRocks はリモートストレージからそれらを取得します。
enable_background_refresh_connector_metadata​
  • 単位: -
  • デフォルト値: true
  • 説明: 定期的な Iceberg メタデータキャッシュのリフレッシュを有効にするかどうか。これが有効になると、StarRocks は Iceberg クラスターのメタストア（Hive Metastore または AWS Glue）をポーリングし、頻繁にアクセスされる Iceberg catalog のキャッシュされたメタデータをリフレッシュしてデータの変更を認識します。true は Iceberg メタデータキャッシュのリフレッシュを有効にし、false はそれを無効にします。
background_refresh_metadata_interval_millis​
  • 単位: ミリ秒
  • デフォルト値: 600000
  • 説明: 2 つの連続した Iceberg メタデータキャッシュリフレッシュの間隔。- 単位: ミリ秒。
background_refresh_metadata_time_secs_since_last_access_sec​
  • 単位: 秒
  • デフォルト値: 86400
  • 説明: Iceberg メタデータキャッシュリフレッシュタスクの有効期限。アクセスされた Iceberg catalog に対して、指定された時間を超えてアクセスされていない場合、StarRocks はそのキャッシュされたメタデータのリフレッシュを停止します。アクセスされていない Iceberg catalog に対して、StarRocks はそのキャッシュされたメタデータをリフレッシュしません。

付録 A: 定期的なメタデータリフレッシュ戦略​

Appendix A: Periodic Metadata Refresh Strategy​

Iceberg は スナップショット をサポートしています。最新のスナップショットでは、最新の結果を得ることができる。したがって、キャッシュされたスナップショットのみがデータの鮮度に影響を与える。その結果、スナップショットを含むキャッシュのリフレッシュ戦略にのみ注意を払う必要がある。

以下のフローチャートは、時間間隔をタイムライン上に示している。

Timeline for updating and discarding cached metadata

付録 B: メタデータファイルのパース​

  • 大量のメタデータに対する分散プラン

    大量のメタデータを効果的に処理するために、StarRocks は複数の BE および CN ノードを使用して分散アプローチを採用しています。この方法は、現代のクエリエンジンの並列計算能力を活用し、マニフェストファイルの読み取り、解凍、フィルタリングなどのタスクを複数のノードに分散させます。これにより、これらのマニフェストファイルを並列に処理することで、メタデータの取得にかかる時間が大幅に短縮され、ジョブプランニングが迅速化されます。これは、多数のマニフェストファイルを含む大規模なクエリに特に有益であり、単一ポイントのボトルネックを排除し、全体的なクエリ実行効率を向上させます。

  • 少量のメタデータに対するローカルプラン

    小規模なクエリでは、マニフェストファイルの繰り返しの解凍と解析が不要な遅延を引き起こす可能性があるため、異なる戦略が採用されます。StarRocks は、特に Avro ファイルのデシリアライズされたメモリオブジェクトをキャッシュすることで、この問題に対処します。これらのデシリアライズされたファイルをメモリに保存することで、後続のクエリでは解凍と解析の段階をバイパスできます。このキャッシングメカニズムにより、必要なメタデータに直接アクセスでき、取得時間が大幅に短縮されます。その結果、システムはより応答性が高くなり、高いクエリ要求やマテリアライズドビューの書き換えニーズにより適しています。

  • 適応型メタデータ取得戦略（デフォルト）

    StarRocks は、FE および BE/CN ノードの数、CPU コア数、現在のクエリに必要なマニフェストファイルの数など、さまざまな要因に基づいて適切なメタデータ取得方法を自動的に選択するように設計されています。この適応型アプローチにより、メタデータ関連のパラメーターを手動で調整することなく、システムが動的にメタデータ取得を最適化します。これにより、StarRocks はシームレスなエクスペリエンスを提供し、分散プランとローカルプランのバランスを取り、さまざまな条件下で最適なクエリパフォーマンスを実現します。

システム変数 plan_mode を使用して Iceberg メタデータキャッシュプランを調整できます。

Rocky the happy otterStarRocks Assistant

AI generated answers are based on docs and other sources. Please test answers in non-production environments.