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

構文¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ COLLATE '<collation_specification>' ]
      [ { DEFAULT <expr>
          | { AUTOINCREMENT | IDENTITY }
            [ { ( <start_num> , <step_num> )
                | START <num> INCREMENT <num>
              } ]
        } ]
      [ [ 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 [ ... ] ]
  )
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  BASE_LOCATION = '<directory_for_table_files>'
  [ 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 } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ 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>' , ... ] ) ]

条件:

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 をご参照ください。

バリアント構文¶

必須パラメーター¶

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 位置からの相対パスを指定します。詳細については、 データとメタデータのディレクトリ をご参照ください。

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

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

CONSTRAINT ...

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

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

COLLATE 'collation_specification'

文字列比較などの列操作に使用する照合順序を指定します。このオプションはテキスト列（VARCHAR、 STRING、 TEXTなど）にのみ適用されます。詳細については、 照合順序仕様 をご参照ください。

DEFAULT ... または . AUTOINCREMENT ...

INSERT または CREATE TABLE AS SELECT ステートメントで値が明示的に指定されていない場合に、デフォルト値を列に自動的に挿入するかどうかを指定します。

DEFAULT expr

列のデフォルト値は、次のいずれかの指定可能な式によって定義されます。

• 定数値。

• シーケンス参照（seq_name.NEXTVAL）。

• スカラー値を返す単純式。

  UDFが セキュアUDF でない場合、単純式にSQL UDF（ユーザー定義関数）を含めることができます。

  注釈

  デフォルトの式が SQL UDF を参照している場合、関数はテーブルの作成時に関数定義よって置き換えられます。ユーザー定義関数が将来再定義される場合は、列のデフォルト式は更新されません。

  単純式 cannot には、次の参照を含めることができません。

  • サブクエリ。

  • 集計。

  • ウィンドウ関数。

  • セキュアUDFs

  • SQL 以外の言語で記述された UDFs （例: Java、JavaScript）。

  • 外部関数。

{ AUTOINCREMENT | IDENTITY } [ { ( start_num , step_num ) | START num INCREMENT num } ]

AUTOINCREMENT と IDENTITY は同義語です。いずれかが使用されている場合、列のデフォルト値は指定された数値で始まり、連続する各値は指定された量だけ自動的に増加します。

注意

Snowflakeはシーケンスを使用して、自動インクリメントされた列の値を生成します。シーケンスには制限があります。 シーケンスのセマンティクス をご参照ください。

開始とステップ/増分の両方のデフォルト値は 1 です。

AUTOINCREMENT および IDENTITY は、数値データ型の列にのみ使用できます。

デフォルト：値なし（列にデフォルト値なし）

注釈

DEFAULT と AUTOINCREMENT は、相互に排他的です。列には1つしか指定できません。

MASKING POLICY = policy_name

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

PROJECTION POLICY policy_name

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

COMMENT 'string_literal'

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

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

USING ( col_name , cond_col_1 ... )

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

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

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

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

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

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

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

重要

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

テーブルのクラスタリングキーを指定する前に、マイクロパーティションについて理解する必要があります。詳細については、 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で管理されたテーブルを Snowflake Open Catalog と同期する をご参照ください。

プレビュー機能

すべてのアカウントで利用可能です。

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

DEFAULT_DDL_COLLATION = 'collation_specification'

将来テーブルに追加される列を含む、テーブルの列のデフォルトの 照合仕様 を指定します。

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

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です。

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

アクセス制御の要件¶

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

スキーマ内の任意のオブジェクトを操作するには、親データベースとスキーマに対する 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 エラー（または同様のタイプのエラー）が発生する可能性があります。

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

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

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

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

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

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

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

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

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

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

  • CREATE ICEBERG TABLE ... ： LIKE:

    • ソーステーブルにクラスタリングキーがある場合は、新しいテーブルにもクラスタリングキーがあります。デフォルトでは、ソーステーブルに対して自動クラスタリングが一時停止されていても、新しいテーブルに対して自動クラスタリングは一時停止されません。

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

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

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

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

    • 特定の順序で行を使用してテーブルを作成する場合は、 CTAS の SELECT 句で ORDER BY サブ句を使用します。CLUSTER BY を指定しても、テーブルの作成時にデータはクラスター化されません。代わりに、 CLUSTER BY は 自動クラスタリング に依存して、時間の経過とともにデータを再クラスタリングします。

      CREATE TABLE ステートメントの ORDER BY サブ句は、そのテーブルの将来の SELECT ステートメントによって返される行の順序には影響しません。将来の SELECT ステートメントで行の順序を指定するには、それらのステートメントで ORDER BY サブ句を使用します。

• メタデータについて:

  注意

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

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