CREATE ICEBERG TABLE （オブジェクトストレージ内のIcebergファイル）¶

構文¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  METADATA_FILE_PATH = '<metadata_file_path>'
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

必須パラメーター¶

table_name

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

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

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

METADATA_FILE_PATH = 'metadata_file_path'

列定義に使用するIcebergメタデータファイルの相対パスを指定します。

例えば、 s3://mybucket_us_east_1/metadata/v1.metadata.json がメタデータファイルへのフルパスで、外部ボリュームのストレージの場所が s3://mybucket_us_east_1/ の場合、 METADATA_FILE_PATH の値として metadata/v1.metadata.json を指定します。

Snowflakeのバージョン7.34より前では、このパラメーターは METADATA_FILE_NAME と呼ばれていました。

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

EXTERNAL_VOLUME = 'external_volume_name'

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

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

CATALOG = 'catalog_integration_name'

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

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

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

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

• TRUE の場合は、無効な UTF -8文字がUnicode置換文字に置き換えられます。

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

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

デフォルト: FALSE

COMMENT = 'string_literal'

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

デフォルト: 値なし

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

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

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

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

アクセス制御の要件¶

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

スキーマ内の任意のオブジェクトを操作するには、親データベースとスキーマに対する USAGE 権限も必要であることに注意してください。

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

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

使用上の注意¶

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

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

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

  • Snowflakeのバージョン7.34以降では、オブジェクトストレージのIcebergファイルからテーブルを作成する際に BASE_LOCATION を指定 しません。

    バージョン7.34より前では、オブジェクトストレージ内のIcebergファイルからテーブルを作成するには BASE_LOCATION （以前のバージョンでは FILE_PATH とも呼ばれていました）というパラメーターが必要でした。パラメーターは、 EXTERNAL_VOLUME の場所からの相対パスを指定しました。

    従来の構文を使用するスクリプトやステートメントを引き続き実行できます。その場合、以下の注意事項が適用されます。

    • テーブルのParquetデータファイルとIcebergメタデータファイルは、 BASE_LOCATION 内にある必要があります。

    • テーブルをリフレッシュするには、 BASE_LOCATION と 相対的 なパスを指定する必要があります。例えば、メタデータファイルのフルパスが s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json の場合、 metadata/v1.metadata.json を metadata-file-relative-path として指定します。

      詳細については、 ALTER ICEBERG TABLE ... REFRESH をご参照ください。

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

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

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

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

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

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

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

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

• メタデータについて:

  注意

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

例¶

CREATE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME='my_external_volume'
  CATALOG='my_catalog_integration'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"external_volume_1"'
  CATALOG = '"catalog_integration_1"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';