CREATE ICEBERG TABLE (Iceberg REST カタログ)¶

現行/指定スキーマで、Iceberg REST カタログ用の Apache Iceberg™ テーブルを作成または置換します。

このコマンドは以下のシナリオで使用します。

オープンソースの Apache Iceberg REST OpenAPI 仕様に準拠したリモートの Iceberg カタログを使用したい場合。
Snowflake Open Catalog またはApache Polaris™のテーブルをクエリしたい場合。詳細については、 Snowflakeを使用して Snowflake Open Catalog 内のテーブルをクエリするをご参照ください。
カタログリンクデータベースで書き込みサポート付きの外部管理テーブルを作成したい場合。CREATE ICEBERG TABLE（カタログリンクデータベース）をご参照ください。

注釈

テーブルを作成する前に、Icebergメタデータとデータファイルを格納する外部ボリュームを作成する必要があります。手順については、外部ボリュームの構成をご参照ください。

また、テーブルのカタログ統合も必要です。詳細については、 Apache Iceberg™ REST カタログのカタログ統合を構成するまたは Snowflake Open Catalog のカタログ統合を設定するをご参照ください。

こちらもご参照ください。: ALTER ICEBERG TABLE、 DROP ICEBERG TABLE、 SHOW ICEBERG TABLES、 DESCRIBE ICEBERG TABLE、 UNDROP ICEBERG TABLE

構文¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<rest_catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Copy

バリアント構文¶

CREATE ICEBERG TABLE（カタログリンクデータベース）¶

CREATE ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [
    --Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]
  ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

CREATE ICEBERG TABLE（カタログリンクデータベース）... AS SELECT¶

CREATE ICEBERG TABLE <table_name> [ ( <col_name> [ <col_type> ] , <col_name> [ <col_type> ] , ... ) ]
  [ ... ]
  AS SELECT <query>

Copy

マスキングポリシーを CTAS ステートメントの列に適用できます。列のデータ型の後にマスキングポリシーを指定します。例:

CREATE ICEBERG TABLE <table_name> ( <col1> <data_type> [ WITH ] MASKING POLICY <policy_name> [ , ... ] )
  [ ... ]
  AS SELECT <query>

Copy

必須パラメーター¶

table_name

Snowflakeのテーブルの識別子（名前）を指定します。テーブルが作成されるスキーマに対して一意である必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、識別子の要件をご参照ください。

注釈

リモート・カタログのテーブルまたは名前空間のリストを取得するには、以下の関数を使用します。

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

外部カタログで認識されるテーブル名を指定します。このパラメーターはテーブル作成後に変更することはできません。

注釈

テーブル名（mynamespace.mytable）で名前空間を指定しないでください。このテーブルに名前空間を指定し、カタログ統合で設定されたデフォルトの名前空間をオーバーライドするには、 CATALOG_NAMESPACE パラメーターを使用します。

col_name

:doc:`カタログリンクデータベース（プレビュー）</user-guide/tables-iceberg-catalog-linked-database> ` のテーブルを作成する場合。

列の識別子（名前）を指定します。テーブル識別子のすべての要件は、列識別子にも適用されます。

詳細については、識別子の要件および予約および制限されたキーワードをご参照ください。

注釈

標準の予約キーワードに加えて、次のキーワードは ANSI 標準コンテキスト関数用に予約されているため、列識別子として使用できません。

CURRENT_DATE
CURRENT_ROLE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_USER

予約済みキーワードのリストについては、予約および制限されたキーワードをご参照ください。

col_type

:doc:`カタログリンクデータベース（プレビュー）</user-guide/tables-iceberg-catalog-linked-database> ` のテーブルを作成する場合。

列のデータ型を指定します。

テーブル列に指定できるデータ型の情報については、 Apache Iceberg™ テーブルのデータ型をご参照ください。

オプションのパラメーター¶

MASKING POLICY = policy_name

:doc:`カタログリンクデータベース（プレビュー）</user-guide/tables-iceberg-catalog-linked-database> ` のテーブルを作成する場合。

列に設定するマスキングポリシーを指定します。マスキングポリシーは、標準のSnowflakeデータベース（カタログリンクデータベースではない）に属している必要があります。

EXTERNAL_VOLUME = 'external_volume_name'

IcebergテーブルがメタデータファイルとデータをParquet形式で保存する外部ボリュームの識別子（名前）を指定します。Icebergのメタデータとマニフェストファイルには、テーブルスキーマ、パーティション、スナップショット、その他のメタデータが格納されています。

このパラメーターを指定しない場合、Icebergテーブルのデフォルトはスキーマ、データベース、またはアカウントの外部ボリュームになります。スキーマはデータベースより優先され、データベースはアカウントより優先されます。

CATALOG = 'catalog_integration_name'

このテーブルのカタログ統合の識別子（名前）を指定します。

CATALOG_NAMESPACE = 'catalog_namespace'

オプションで、 REST カタログソースの名前空間（my_database など）を指定します。カタログ統合で名前空間を指定し、その後テーブルレベルで指定することにより、1つの REST カタログ統合を使用して、異なるデータベース間でIcebergテーブルを作成できます。テーブルで名前空間を指定しない場合、テーブルはカタログ統合に関連付けられたデフォルトのカタログ名前空間を使用します。
カタログ統合でデフォルトの名前空間が指定されていない場合は、 REST カタログソースの名前空間を指定して、テーブルにカタログ名前空間を設定する必要があります。

注釈

リモート・カタログのテーブルまたは名前空間のリストを取得するには、以下の関数を使用します。

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

テーブルのターゲットParquetファイルサイズを指定します。

:code:`'{ 16MB | 32MB | 64MB | 128MB }'`では、テーブルのターゲットファイルサイズを固定して指定します。
'AUTO' は、テーブルタイプに応じて動作が異なります。
- Snowflake 管理テーブル: AUTO は、サイズ、DML パターン、取り込みワークロード、クラスタリング構成などのテーブル特性に基づいて、Snowflakeがテーブルのファイルサイズを選択することを指定します。Snowflakeは、Snowflakeでの読み取りと書き込みパフォーマンスを向上させるために、ファイルサイズを16 MB を起点として自動的に調整します。このオプションを使用して、Snowflakeでテーブルのパフォーマンスを最適化します。
- 外部管理テーブル: AUTO は、Snowflakeが最大のファイルサイズ（128MB）に積極的にスケーリングすることを指定します。

詳細については、ターゲットファイルサイズの設定をご参照ください。

デフォルト: AUTO

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Snowflakeがテーブルのデータ保持期間を延長してテーブル上のストリームが古くなるのを防ぐことができる最大日数を指定するオブジェクトパラメーター。

このパラメーターの詳細については、 MAX_DATA_EXTENSION_TIME_IN_DAYS をご参照ください。

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

クエリ結果で、無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定します。このパラメーターを設定できるのは、外部Icebergカタログを使用するテーブルのみです。

TRUE の場合は、無効な UTF -8文字がUnicode置換文字に置き換えられます。
FALSE の場合は、無効な UTF -8 文字は変更されません。Parquetデータファイルで無効な UTF -8 文字が検出された場合、Snowflakeはユーザーエラーメッセージを返します。

指定しない場合、Icebergテーブルのデフォルトはスキーマ、データベース、またはアカウントのパラメーター値になります。スキーマはデータベースより優先され、データベースはアカウントより優先されます。

デフォルト: FALSE

AUTO_REFRESH = { TRUE | FALSE }

メタデータの更新のために、Snowflake がテーブルに関連付けられた外部 Iceberg カタログを自動的にポーリングするかどうかを指定します。

カタログ統合の REFRESH_INTERVAL_SECONDS パラメータに値が指定されていない場合、Snowflake はデフォルトの更新間隔 30 秒を使用します。

詳細については、自動更新をご参照ください。

デフォルト: FALSE

注釈

AUTO_REFRESHを INFER_SCHEMAで使用することはサポートされていません。

COPY GRANTS

次の CREATE TABLE バリアントのいずれかを使用して新しいテーブルが作成されるときに、元のテーブルからのアクセス権限を保持することを指定します。

CREATE OR REPLACE TABLE

このパラメーターは、既存のテーブルから新しいテーブルにすべての権限（OWNERSHIP 以外）をコピーします。新しいテーブルは、スキーマ内のオブジェクトタイプに定義された将来の許可を継承しません。デフォルトでは、 CREATE TABLE ステートメントを実行するロールが新しいテーブルを所有します。

パラメーターが CREATE ICEBERG TABLE ステートメントに含まれていない場合、新しいテーブルは元のテーブルに付与された明示的なアクセス権限を継承しませんが、スキーマ内のオブジェクトタイプに定義された将来の権限は継承します。

注意:

データ共有の場合、
- 既存のテーブルが別のアカウントと共有されていた場合、置換テーブルも共有されます。
- 既存のテーブルがデータコンシューマとしてアカウントと共有され、アクセスがアカウント内の他のロールにさらに許可された場合（親データベースの GRANT IMPORTED PRIVILEGES を使用）、置換テーブルにもアクセスが許可されます。
置換テーブルの SHOW GRANTS 出力には、コピーされた権限の被付与者が、ステートメントが実行されたときの現在のタイムスタンプとともに、 CREATE ICEBERG TABLE ステートメントを実行したロールとしてリストされます。
付与をコピーする操作は、 CREATE ICEBERGTABLE コマンドで（つまり、同じトランザクション内で）アトミックに発生します。

COMMENT = 'string_literal'

テーブルのコメントを指定します。

デフォルト: 値なし

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

タグの名前とタグ文字列の値を指定します。

タグ値は常に文字列であり、タグ値の最大文字数は256です。

ステートメントでのタグの指定に関する情報については、オブジェクトのタグクォータをご参照ください。

WITH CONTACT ( purpose = contact [ , purpose = contact ...] ): 新しいオブジェクトを1つ以上の連絡先に関連付けます。

アクセス制御の要件¶

この操作の実行に使用されるロールには、少なくとも次の権限が必要です。

権限	オブジェクト	注意
CREATE ICEBERG TABLE	スキーマ
CREATE EXTERNAL VOLUME	アカウント	新しい外部ボリュームを作成するために必要です。
USAGE	外部ボリューム	既存の外部ボリュームを参照するために必要です。
CREATE INTEGRATION	アカウント	新しいカタログ統合を作成するために必要です。
USAGE	カタログ統合	既存のカタログ統合を参照するために必要です。

スキーマ内のオブジェクトに対して操作を実行するには、親データベースとスキーマに対する USAGE 権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、カスタムロールの作成をご参照ください。

セキュリティ保護可能なオブジェクトに対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、アクセス制御の概要をご参照ください。

使用上の注意¶

例¶

リモートのIceberg REST カタログを使用するIcebergテーブルを作成する¶

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

Copy

Snowflake Open Catalog のテーブルをクエリするためにIcebergテーブルを作成する¶

この例では、 Snowflakeを使用して Snowflake Open Catalog 内のテーブルをクエリするに使用できるIceberg テーブルを作成します。

CREATE ICEBERG TABLE open_catalog_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'open_catalog_int'
  CATALOG_TABLE_NAME = 'my_open_catalog_table'
  AUTO_REFRESH = TRUE;

Copy

カタログリンクデータベースでのIcebergテーブルの作成¶

次の例では、列定義のあるカタログリンクデータベースで書き込み可能なIcebergテーブルを作成します。

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
);

Copy