メインコンテンツまでスキップ

Iceberg catalog

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

  • Iceberg に保存されたデータを直接クエリし、手動でテーブルを作成する必要がありません。
  • INSERT INTO または非同期マテリアライズドビュー（v2.5 以降でサポート）を使用して、Iceberg に保存されたデータを処理し、StarRocks にデータをロードします。
  • 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",
    MetastoreParams,
    StorageCredentialParams,
    MetadataRelatedParams
)

パラメータ​

catalog_name​

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

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

comment​

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

type​

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

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

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_cachetrueTable Cache、Partition Name Cache、および Manifest 内の Data File Cache と Delete Data File Cache を含む Iceberg 関連のメタデータをキャッシュするかどうか。
iceberg_manifest_cache_with_column_statisticsfalse列の統計情報をキャッシュするかどうか。
iceberg_manifest_cache_max_num100000キャッシュできる Manifest ファイルの最大数。
refresh_iceberg_manifest_min_length2 * 1024 * 1024Data File Cache の更新をトリガーする最小の Manifest ファイルの長さ。

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

catalog の使用​

Iceberg catalog の表示​

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

SHOW CATALOGS;

外部 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 の削除​

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

  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 権限を持っている場合、その Iceberg catalog 内でデータベースを作成するために CREATE DATABASE ステートメントを使用できます。この機能は 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 権限を持っている場合、その Iceberg データベースを削除するために DROP DATABASE ステートメントを使用できます。この機能は v3.1 以降でサポートされています。空のデータベースのみを削除できます。

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

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

DROP DATABASE <database_name>;

Iceberg テーブルの作成​

StarRocks の内部データベースと同様に、Iceberg データベースに対して CREATE TABLE 権限を持っている場合、その Iceberg データベース内でテーブルを作成するために CREATE TABLE または [CREATE TABLE AS SELECT ../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.mdELECT.md) ステートメントを使用できます。この機能は 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]
[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 (par_col1[, par_col2...])

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

注記

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

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;

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

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

Iceberg catalog とそのデータベースに切り替える してから、次の構文を使用して StarRocks テーブルのデータをそのデータベース内の Parquet 形式の 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 }
注記

パーティション列は 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 の2つの条件を満たすパーティションに 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 の2つの条件を満たすパーティションのすべての 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 権限を持っている場合、その Iceberg テーブルを削除するために DROP TABLE ステートメントを使用できます。この機能は v3.1 以降でサポートされています。

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

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

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

DROP TABLE <table_name> [FORCE];

メタデータキャッシュの設定​

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

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

  • 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 メタデータキャッシュプランを調整できます。