CREATE ICEBERG TABLE （IcebergカタログとしてのSnowflake）¶

構文¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] PROJECTION POLICY <policy_name> ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ PARTITION BY ( partitionExpression [, partitionExpression , ...] ) ]
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  [ BASE_LOCATION = '<directory_for_table_files>' ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] AGGREGATION POLICY <policy_name> ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]
  [ ENABLE_DATA_COMPACTION = { TRUE | FALSE } ]

条件:

inlineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE
    | PRIMARY KEY
    | [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ]
  }
  [ <constraint_properties> ]

Copy

インライン制約の詳細については、 CREATE | ALTER TABLE ... CONSTRAINT をご参照ください。

outoflineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE [ ( <col_name> [ , <col_name> , ... ] ) ]
    | PRIMARY KEY [ ( <col_name> [ , <col_name> , ... ] ) ]
    | [ FOREIGN KEY ] [ ( <col_name> [ , <col_name> , ... ] ) ]
      REFERENCES <ref_table_name> [ ( <ref_col_name> [ , <ref_col_name> , ... ] ) ]
  }
  [ <constraint_properties> ]

Copy

注釈

• Snowflakeは、 PRIMARY KEY として定義された列をIcebergメタデータの識別子フィールドとして表します。これらの列の IDs は、 識別子フィールド IDs としてメタデータに入力されます。

• SnowflakeはIcebergテーブルの PRIMARY KEY 列に対して、 NOT NULL および UNIQUE 制約を強制しません。

アウトライン制約の詳細については、 CREATE | ALTER TABLE ... CONSTRAINT をご参照ください。

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

Copy

バリアント構文¶

必須パラメーター¶

table_name

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

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

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

col_name

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

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

注釈

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

• CURRENT_DATE

• CURRENT_ROLE

• CURRENT_TIME

• CURRENT_TIMESTAMP

• CURRENT_USER

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

col_type

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

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

注釈

float や double を主キーとして使用することはできません（Apache Iceberg仕様 に準拠）。

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

BASE_LOCATION = 'directory_for_table_files'

Snowflakeがテーブルのデータファイルとメタデータファイルの書き込みパスを構築するために使用するディレクトリへのパス。テーブルの EXTERNAL_VOLUME 位置からの相対パスを指定します。

指定がない場合、Snowflakeは BASE_LOCATION_PREFIX パラメーターの値やテーブル名などの属性を使用して書き込みパスを構築します。

詳細については、 データとメタデータのディレクトリ をご参照ください。

このディレクトリをテーブル作成後に変更することはできません。

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

CONSTRAINT ...

テーブル内の指定された列のインラインまたはアウトライン制約を定義します。

構文の情報については、 CREATE | ALTER TABLE ... CONSTRAINT をご参照ください。制約の詳細については、 制約 をご参照ください。

MASKING POLICY = policy_name

列に設定する マスキングポリシー を指定します。

PROJECTION POLICY policy_name

列に設定する 投影ポリシー を指定します。

COMMENT 'string_literal'

列のコメントを指定します。

（コメントは列レベルまたはテーブルレベルで指定できることに注意してください。それぞれの構文は少し異なります。）

USING ( col_name , cond_col_1 ... )

条件付きマスキングポリシーのために SQL 式に渡す引数を指定します。

リストの最初の列は、データをマスクまたはトークン化するポリシー条件の列を指定し、マスキングポリシーが設定されている列と一致する 必要 があります。

追加の列は、クエリが最初の列から選択するときに、クエリ結果の各行のデータをマスクするかトークン化するかを決定するために評価する列を指定します。

USING 句が省略されている場合、Snowflakeは条件付きマスキングポリシーを通常の マスキングポリシー として扱います。

PARTITION BY = ( partitionExpression [ , partitionExpression , ... ] )

1つ以上の パーティション式 を指定します。

CLUSTER BY ( expr [ , expr , ... ] )

テーブル内の1つ以上の列または列式をクラスタリングキーとして指定します。詳細については、 クラスタリングキーとクラスタ化されたテーブル をご参照ください。

バリアント構文（LIKE、 AS SELECT）を使用する場合は、 バリアント構文の使用上の注意 をご参照ください。

デフォルト：値なし（テーブルにクラスタリングキーが定義されていない）

重要

クラスタリングキーは、すべてのテーブルに対して意図または推奨されているわけでは ありません。通常、非常に大きな（つまり、マルチテラバイト）テーブルに役立ちます。

テーブルのクラスタリングキーを指定する前に、マイクロパーティションについて理解する必要があります。詳細については、 Snowflakeテーブル構造について をご参照ください。

EXTERNAL_VOLUME = 'external_volume_name'

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

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

CATALOG = 'SNOWFLAKE'

SnowflakeをIcebergカタログに指定します。Snowflakeがテーブルのコンパクションなど、ライフサイクルのメンテナンスをすべて行います。

CATALOG_SYNC = 'open_catalog_integration_name'

オプションで、 Snowflake Open Catalog 用に構成されたカタログ統合の名前を指定します。指定された場合、Snowflake は Snowflake Open Catalog アカウントの外部カタログとテーブルを同期します。Snowflake管理のIcebergテーブルとOpen Catalogの同期に関する情報については、 Snowflakeで管理されたテーブルを Snowflake Open Catalog と同期する をご参照ください。

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

STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED }

テーブルのストレージシリアル化ポリシーを指定します。テーブル作成時に指定しなかった場合、テーブルはスキーマ、データベース、またはアカウントレベルで設定された値を継承します。どのレベルでも値が指定されていない場合、テーブルではデフォルト値が使用されます。

テーブル作成後にこのパラメーターの値を変更することはできません。

• COMPATIBLE:Snowflakeは、サードパーティのコンピューティングエンジンとの相互運用性を実現するエンコードと圧縮を実行します。

• OPTIMIZED:Snowflakeは、Snowflake内で優れたテーブルパフォーマンスを実現するエンコードと圧縮を実行します。

デフォルト: OPTIMIZED

DATA_RETENTION_TIME_IN_DAYS = integer

Snowflake管理テーブルの履歴データに対してTime Travelアクション（SELECT、 CLONE、 UNDROP）を実行できるように、テーブルの保持期間を指定します。詳細については、 Time Travelの理解と使用 をご参照ください。

このオブジェクトレベルパラメーターの詳細な説明、およびオブジェクトパラメーターの詳細については、 パラメーター をご参照ください。

値：

• Standard Edition： 0 または 1

• Enterprise Edition: 永続テーブルの場合は 0 ～ 90

デフォルト：

• Standard Edition： 1

• Enterprise Edition（またはそれ以上）： 1 （スキーマ、データベースまたはアカウントレベルで別のデフォルト値が指定されていない場合）

注釈

0 の値は、テーブルのTime Travelを効果的に無効化します。

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

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

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

CHANGE_TRACKING = { TRUE | FALSE }

テーブルで変更追跡を有効にするかどうかを指定します。

• TRUE テーブルの変更追跡を有効にします。この設定により、非表示の列のペアがソーステーブルに追加され、変更追跡メタデータの列への保存が開始されます。これらの列は少量のストレージを消費します。

  変更追跡メタデータのクエリには、 SELECT ステートメントの CHANGES 句を使用するか、テーブルで1つ以上のストリームを作成し、クエリします。

• FALSE は、テーブルの変更追跡を有効にしません。

デフォルト: FALSE

COPY GRANTS

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

• CREATE OR REPLACE TABLE

• CREATE TABLE ... LIKE

• CREATE TABLE ... CLONE

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

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

注意：

• データ共有 の場合、

  • 既存のテーブルが別のアカウントと共有されていた場合、置換テーブルも共有されます。

  • 既存のテーブルがデータコンシューマとしてアカウントと共有され、アクセスがアカウント内の他のロールにさらに許可された場合（親データベースの GRANT IMPORTED PRIVILEGES を使用）、置換テーブルにもアクセスが許可されます。

• 置換テーブルの SHOW GRANTS 出力には、コピーされた権限の被付与者が、ステートメントが実行されたときの現在のタイムスタンプとともに、 CREATE ICEBERG TABLE ステートメントを実行したロールとしてリストされます。

• 付与をコピーする操作は、 CREATE ICEBERGTABLE コマンドで（つまり、同じトランザクション内で）アトミックに発生します。

COMMENT = 'string_literal'

コメントを指定します。コメントは列レベルまたはテーブルレベルで指定できます。それぞれの構文は若干異なります。

デフォルト: 値なし

ROW ACCESS POLICY policy_name ON ( col_name [ , col_name ... ] )

テーブルに設定する 行アクセスポリシー を指定します。

AGGREGATION POLICY policy_name

テーブルに設定する 集計ポリシー を指定します。

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

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

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

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

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

新しいオブジェクトを1つ以上の 連絡先 に関連付けます。

ENABLE_DATA_COMPACTION = { TRUE | FALSE }

Snowflakeがテーブルでデータ圧縮を有効にするかどうかを指定します。

• TRUE:Snowflakeはテーブルでデータ圧縮を実行します。

• FALSE: Snowflakeはテーブルでデータ圧縮を実行しません。

デフォルト: TRUE

詳細については、 ENABLE_DATA_COMPACTION および データ圧縮の設定 をご参照ください。

パーティション式パラメーター（partitionExpression）¶

Icebergテーブルのパーティション分割の詳細については、Icebergパーティショニング をご参照ください。

col_name

パーティション化するソース列の識別子（名前）を指定します。

YEAR などの変換なしで、単独で使用する場合は、ソース列でのID変換を指定します。詳細については、ID をご参照ください。

BUCKET

バケット変換を指定します。詳細については、バケット変換の詳細 をご参照ください。

num_buckets は、データをグループ化するバケットの数です。

TRUNCATE

指定されたソース列の切り捨て値に基づいてデータをパーティション化する切り捨て変換を指定します。詳細については、変換の詳細を切り捨てる をご参照ください。

YEAR

日付またはタイムスタンプのソース列値から年を抽出する年変換を指定します。詳細については、パーティション変換 をご参照ください。

MONTH

月の変換を指定します。詳細については、パーティション変換 をご参照ください。

DAY

日付またはタイムスタンプのソース列値から日を抽出する日変換を指定します。詳細については、パーティション変換 をご参照ください。

HOUR

タイムスタンプソース列値から時間を抽出する時間変換を指定します。詳細については、パーティション変換 をご参照ください。

アクセス制御の要件¶

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

スキーマ内のオブジェクトに対して操作を実行するには、親データベースとスキーマに対する USAGE 権限が必要です。スキーマに対する任意の権限を付与されたロールは、そのロールがスキーマを解決できることに注意してください。たとえば、スキーマに対する CREATE 権限を付与されたロールは、そのスキーマにオブジェクトを作成できますが、そのスキーマに対する USAGE*も*付与されている必要はありません。

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

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

使用上の注意¶

• このコマンドを実行する際の注意事項:

  • SnowflakeをIcebergカタログとして使用する場合、クロスクラウドおよびクロスリージョンのIcebergテーブルは現在サポートされていません。CREATE ICEBERG TABLE が "External volume <ボリューム名 > must have a STORAGE_LOCATION defined in the local region ..." などのエラーメッセージを返す場合、外部ボリュームがSnowflakeアカウントと同じリージョンにあるアクティブなストレージの場所を使用していることを確認してください。

  • 二重引用符で囲まれた識別子を使用して外部ボリュームを作成した場合は、 CREATE ICEBERG TABLE ステートメントで作成した識別子と（二重引用符を含めて） まったく同じ 識別子を指定する必要があります。引用符を含めないと、 Object does not exist エラー（または同様のタイプのエラー）が発生する可能性があります。

    例については、 例 （このトピックの）セクションをご参照ください。

  • USING TEMPLATE 句（および INFER_SCHEMA 出力から派生した列定義）を持つ Icebergテーブル を作成するには、 INFER_SCHEMA 関数に KIND => 'ICEBERG' を指定する必要があります。

• テーブルの作成に関する考慮事項:

  • スキーマに同じ名前のテーブルやビューを含めることはできません。テーブルを作成する場合：

    • 同じ名前のビューがスキーマにすでに存在する場合は、エラーが返され、テーブルは作成されません。

    • 同じ名前のテーブルがスキーマに既に存在する場合、オプションの OR REPLACE キーワードがコマンドに含まれていない限り、エラーが返され、テーブルは作成されません。

  • CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

    これは、 CREATE OR REPLACE ICEBERG TABLE 操作と同時に実行されるクエリが、古いテーブルバージョンまたは新しいテーブルバージョンのいずれかを使用することを意味します。

  • OR REPLACE と IF NOT EXISTS 句は互いに排他的です。両方を同じステートメントで使うことはできません。

  • 予約キーワード と同様に、 ANSI 予約関数名（CURRENT_DATE、 CURRENT_TIMESTAMP など）は列名として使用できません。

  • テーブルを再作成すると（オプションの OR REPLACE キーワードを使用）、その履歴が削除され、テーブル上のストリームが古くなります。古いストリームは読み取れません。

• バリアント構文の使用:

  • CREATE ICEBERG TABLE ... ： LIKE:

    • クラスタリングキーを指定しない場合、テーブルはソーステーブルのクラスタリングキーを継承します（存在する場合）。

    • デフォルトでは、ソーステーブルに対して自動クラスタリングが中断されていたとしても、新しいテーブルに対して 自動クラスタリング は中断されません。

    • パーティション化されたIcebergテーブル の場合、ソーステーブルのパーティション分割は無視されます。この動作をオーバーライドするには、コマンドを使用した PARTITION BY 句を指定します。

  • CREATE ICEBERG TABLE ... AS SELECT (CTAS):

    クラスタリングキーが CTAS ステートメントで指定されている場合、

    • 列定義は必須であり、ステートメントで明示的に指定する必要があります。

    • デフォルトでは、ソーステーブルに対して自動クラスタリングが中断されていたとしても、新しいテーブルに対して 自動クラスタリング は有効になっています。

    • 新しいテーブルが作成されると、データはクラスター化されます。クラスター化されたテーブルは、ソート操作を含むクエリプランを生成し、クラスター化されていない同等のテーブルよりも作成に時間がかかります。

      あるいは、CTAS クエリの ORDER BY 句を使用して、行を並べ替えたテーブルを作成できます。

  • CREATE ICEBERG TABLE ... CLONE:

    • パーティション化されたIcebergテーブル の場合、クローンされたテーブルは、ソーステーブルのパーティション分割情報を保持します。

• メタデータについて:

  注意

  Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

• Snowflake Open Catalog と同期するテーブルを作成する場合は、以下の点に注意してください。

  重要

  オープンカタログのアクセス権限がテーブルに正しく適用されるようにするには、テーブルを作成する前に、そのテーブルが特定の条件を満たしていることを確認してください。これらの条件は、カタログのディレクトリ構造階層に関連しています。これらの条件および条件を満たす方法については、Snowflake Open Catalogドキュメントの カタログコンテンツを整理する の注記をご参照ください。

Snowflake 管理テーブルの作成に関する問題のトラブルシューティングについては、 Snowflake管理テーブルが作成できない をご参照ください。

例¶

CREATE ICEBERG TABLE my_iceberg_table (amount int)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = 'my_iceberg_table';

CREATE OR REPLACE ICEBERG TABLE customer_iceberg_partitioned (
  c_custkey INTEGER,
  c_name STRING,
  c_address STRING,
  c_nationkey INTEGER,
  c_phone STRING,
  c_acctbal INTEGER,
  c_mktsegment STRING,
  c_comment STRING
)
  PARTITION BY (c_nationkey)
  EXTERNAL_VOLUME = 'my_ext_vol'
  CATALOG = 'SNOWFLAKE'
  BASE_LOCATION = 'customer_iceberg_partitioned';

CREATE OR REPLACE ICEBERG TABLE iceberg_table_copy (column1 int)
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'SNOWFLAKE'
  BASE_LOCATION = 'iceberg_table_copy'
  AS SELECT * FROM base_iceberg_table;

CREATE OR REPLACE ICEBERG TABLE table_with_quoted_external_volume
  EXTERNAL_VOLUME = '"external_volume_1"'
  CATALOG = 'SNOWFLAKE'
  BASE_LOCATION = 'my/relative/path/from/external_volume';