外部管理 Apache Iceberg™ テーブルへの書き込みサポート¶
外部管理 Apache Iceberg™ テーブル テーブルへの書き込みサポートにより、外部Iceberg REST カタログで管理されているテーブルに対して書き込み操作を実行できます。SnowflakeのIcebergテーブルはリモートカタログのテーブルにリンクされています。Snowflakeでテーブルに変更を加えると、Snowflakeは同じ変更をリモートカタログにコミットします。
このプレビュー機能は、Snowflakeとサードパーティシステム間の相互運用性を拡張し、外部Icebergカタログを使用する場合でも、Icebergを使用してデータエンジニアリングワークロードにSnowflakeを使用できるようにします。
主なユースケースには、次が含まれます。
Icebergテーブルによる複雑なデータエンジニアリングパイプラインの構築:Snowflakeから外部カタログのIcebergテーブルに書き込むと、SnowparkまたはSnowflake SQL を使用して、Icebergテーブルのデータの取り込み、変換、処理を実行する複雑なパイプラインを構築できます。Snowflakeまたはその他のエンジンを使用してデータをクエリできます。同様に、Snowflake :doc:` パートナーツール </user-guide/ecosystem-all>` を使用してIcebergデータエンジニアリングパイプラインを構築できます。
Icebergエコシステムでデータを利用できるようにする:外部カタログのIcebergテーブルに書き込む機能により、Icebergエコシステムでデータを利用できるようになります。既にSnowflakeにあるデータをクエリし、Icebergテーブルに書き込むことができます。IcebergテーブルとSnowflakeテーブルの同期を維持するには、INSERT INTO … SELECT FROM などの操作を使用して、次を実行します。
標準のSnowflakeテーブルからIcebergテーブルに既存のデータをコピーします。
Snowflakeストリームを使用してデータを挿入します。
考慮事項¶
外部で管理されるIcebergテーブルへの書き込みサポートを使用する場合は、次の点に留意してください。
Snowflakeは外部管理テーブル用のデータ定義言語(DDL)コマンドとデータ操作言語(DML)コマンドを提供しています。ただし、メタデータとデータ保持は、外部カタログと外部ストレージプロバイダーが提供するツールを使用して構成します。詳細については、 外部カタログを使用するテーブル をご参照ください。
書き込みの場合、Snowflakeは、Snowflake内のテーブルを更新する前に、変更がリモートカタログにコミットされるようにします。
カタログリンクデータベースを使用する場合は、列定義を含む CREATE ICEBERG TABLE 構文を使用して、Snowflakeとリモートカタログの両方にテーブルを作成できます。標準のSnowflakeデータベース(カタログにリンクされていない)を使用する場合は、まずリモートカタログでテーブルを作成する必要があります。その後、CREATE ICEBERG TABLE (Iceberg REST カタログ) 構文を使用してSnowflakeにIcebergテーブルを作成し、そこに書き込むことができます。
AWS Glueデータカタログの場合:Snowflakeを介して外部管理テーブルを削除しても、基になるテーブルファイルは削除されません。この動作は、AWS Glueデータカタログ実装に固有のものです。
この機能のプライベートプレビューに参加していた場合、位置指定による行単位削除がアカウントでデフォルトで有効になっている可能性があります。確認するには、次のコマンドを実行します。
SHOW PARAMETERS LIKE 'ENABLE_ICEBERG_MERGE_ON_READ' IN ACCOUNT;
アカウントにパラメーターが表示されている場合は(その値に関係なく)、位置指定による削除が有効になります。位置指定による削除を無効にするには、テーブル、スキーマ、またはデータベースレベルで
ENABLE_ICEBERG_MERGE_ON_READ
パラメーターを FALSE に設定します。以下のIcebergデータ型を使用した外部管理テーブルへの書き込みはサポートされていません。
uuid
fixed(L)
Snowflakeを使用して外部管理Icebergテーブルに書き込む場合、以下の機能は現在サポートされていません。
カタログ提供の認証情報。
GCS またはAzure外部ボリュームのサーバー側暗号化(SSE)。
複数ステートメントトランザクション。Snowflakeは自動コミットトランザクションのみをサポートしています。
Snowflake管理テーブルへの変換。
Iceberg REST プロトコルに準拠していない外部Icebergカタログ。
行レベルの削除(読み取り時のマージ)。
テーブル作成時に OR REPLACE オプションを使用する。
リモートカタログとして AWS Glueを使用する場合は、CREATE TABLE ... AS SELECT 構文を使用します。
カタログリンクデータベースにスキーマを作成する場合は、次の点に注意してください。
CREATESCHEMA コマンドは、カタログリンクデータベースを使用する場合にのみ、リモートカタログに対応する名前空間を作成します。
ALTER および CLONE オプションはサポートされていません。
区切り文字はスキーマ名ではサポートされていません。英数字のスキーマ名のみがサポートされています。
テーブルのParquetファイルのターゲットファイルサイズを設定できます。詳細については、 ターゲットファイルサイズの設定 をご参照ください。
ワークフロー¶
この機能を使い始めるには、このセクションのワークフローを使用します。
次のオプションから選択します。
カタログリンクのデータベースの作成.このオプションを使用すると、カタログで自動検出されたIcebergテーブルに書き込んだり、カタログリンクデータベースを使用して追加のIcebergテーブルを作成したりできます。
:ref:`Icebergテーブルの作成 <label-tables_iceberg_external_writes_create_table>`(カタログリンクデータベースまたは標準のSnowflakeデータベース内)。このオプションを使用すると、Snowflakeで外部管理のIcebergテーブルを作成する前に、まずリモートカタログでテーブルを作成する必要があります。
これらの手順を完了すると、Icebergテーブルに対して 書き込み操作 を実行できます。
外部管理テーブルへの書き込みのための外部ボリュームの構成¶
外部管理テーブルへの書き込みを有効にするには、Snowflakeサービスプリンシパルの読み取り権限と書き込み権限(Snowflake管理テーブルに必要な権限と同じ権限)の両方で構成された外部ボリュームを使用する必要があります。
Iceberg REST カタログがIcebergデータとメタデータを書き込む保管場所(STORAGE_BASE_URL)を指定します。
たとえば、次のステートメントは、my-iceberg-tables
という名前のバケットへの書き込みアクセスを許可する暗号化されたS3用外部ボリュームを作成します。
CREATE OR REPLACE EXTERNAL VOLUME my_external_volume
STORAGE_LOCATIONS =
(
(
NAME = 'my-s3-us-west-2'
STORAGE_PROVIDER = 'S3'
STORAGE_BASE_URL = 's3://my-iceberg-tables/'
STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-write-access-role'
ENCRYPTION = ( TYPE = 'AWS_SSE_S3' )
)
)
ALLOW_WRITES = TRUE;
注釈
外部ボリュームに読み取り権限と書き込み権限を設定し、ALLOW_WRITES パラメーターを TRUE
に設定する必要があります。
詳細な手順については、以下のトピックをご参照ください。
必要な権限の詳細については、Snowflakeにストレージへのアクセスを付与する をご参照ください。
カタログ統合の構成¶
外部管理されたIcebergテーブルに書き込むには、Snowflakeをリモートカタログに接続するようにカタログ統合を構成する必要があります。
リモートカタログは、Open Catalog や AWS Glue Iceberg REST カタログ のように、オープンソースの Apache Iceberg RESTOpenAPI 仕様 に準拠している必要があります。
カタログ統合を作成するには、次のトピックの手順をご参照ください。
AWS Glue Iceberg REST のカタログ統合の構成読み取りおよび書き込み例の IAM ポリシー の権限を使用します。
注釈
現在 AWS Glue </user-guide/tables-iceberg-configure-catalog-integration-glue>` の :doc:` カタログ統合を使用している場合は、AWS Glue Iceberg REST エンドポイント用に新しい REST カタログ統合を作成する必要があります。
カタログリンクデータベースの作成¶
Snowflakeは、カタログリンクデータベース(外部Iceberg REST カタログと同期されているSnowflakeデータベース)内に書き込み可能な外部管理テーブルの作成をサポートしています。また、Snowflakeがリモートカタログで自動的に検出するIcebergテーブルに書き込むこともできます。詳細については、 Apache Iceberg™ テーブルにはカタログリンクデータベースを使用します をご参照ください。
注釈
あるいは、標準のSnowflakeデータベース に、書き込み可能な外部管理Icebergテーブルを作成することもできます。
次の例では、CREATE DATABASE(カタログリンク) コマンドを使用して、外部ボリュームを使用するカタログリンクデータベースを作成します。
CREATE DATABASE my_catalog_linked_db
LINKED_CATALOG = (
CATALOG = 'glue_rest_catalog_int'
),
EXTERNAL_VOLUME = 'my_external_vol';
外部カタログに名前空間を作成するには、CREATE SCHEMA を使用します。¶
外部カタログでIcebergテーブルを整理するための名前空間を作成するには、カタログリンクデータベースで CREATE SCHEMA コマンドを使用します。コマンドは、リンクされたIceberg REST カタログに名前空間を作成し、Snowflake データベースに対応するスキーマを作成します。
CREATE SCHEMA 'my_namespace';
注釈
スキーマ名は英数字である必要があり、区切り文字を含めることはできません。
DROP SCHEMA¶
DROP SCHEMA コマンドを使用して、カタログリンクデータベースからスキーマを削除すると同時に、リモートカタログから対応する名前空間も削除できます。
DROP SCHEMA 'my_namespace';
Icebergテーブルを作成する¶
Snowflakeから書き込める外部管理Icebergテーブルの作成方法は、使用するデータベースの種類によって異なります。
カタログリンクデータベースを使用する場合は、CREATE ICEBERG TABLE(カタログリンクデータベース) を使用してテーブルを作成し、*同時に*そのテーブルをリモートカタログに登録できます。手順については、 カタログリンクデータベースでのIcebergテーブルの作成 をご参照ください。
標準のSnowflakeデータベース(カタログにリンクされていない)を使用する場合は、先にリモートカタログでテーブルを作成する必要があります。その後、CREATE ICEBERG TABLE (Iceberg REST カタログ) 構文を使用して SnowflakeにIcebergテーブルを作成し、そこに書き込むことができます。手順については、 標準のSnowflakeデータベースにIcebergテーブルを作成する をご参照ください。
カタログリンクデータベースでのIcebergテーブルの作成¶
Snowflakeと外部カタログで同時にテーブルを作成するには、CREATE ICEBERG TABLE(カタログリンクデータベース) コマンドを使用します。
以下の例では、AWS Glue REST 用に以前に作成した外部ボリュームとカタログ統合を使用して、書き込み可能な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
)
TARGET_FILE_SIZE = '64MB';
このコマンドを実行すると、Snowflakeはリモートカタログに新しいIcebergテーブルを作成し、Snowflake内にリンクされた書き込み可能な外部管理テーブルを作成します。
標準のSnowflakeデータベースにIcebergテーブルを作成する¶
標準のSnowflakeデータベースを使用するは、先にリモートカタログにテーブルを作成する必要があります。たとえば、Sparkを使用してIcebergテーブルをOpen Catalogに書き込むことができます。
リモートカタログでテーブルを作成した後、CREATE ICEBERG TABLE (Iceberg REST カタログ) コマンドを使用して、SnowflakeでIcebergテーブルオブジェクトを作成します。CATALOG_TABLE_NAME には、リモートカタログに表示されるテーブルの名前を指定します。
例:
CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
EXTERNAL_VOLUME = 'my_external_volume'
CATALOG = 'my_rest_catalog_integration'
CATALOG_TABLE_NAME = 'my_remote_table_name';
このコマンドを実行すると、Snowflakeはリモートカタログの既存のテーブルにリンクされた、書き込み可能な外部管理テーブルをSnowflakeに作成します。
Icebergテーブルの削除¶
DROP ICEBERG TABLE コマンドを使用して、Snowflakeとリモートカタログから、書き込み可能な外部管理Icebergテーブルを同時に削除できます。
DROP ICEBERG TABLE my_iceberg_table;
Snowflakeはテーブルを削除すると同時に、リモートのIcebergカタログを呼び出して、テーブルを削除し、テーブルの基盤となるデータとメタデータを削除するように指示します。
Snowflakeは、テーブルがリモートカタログから正常に削除されたことを確認した後にのみ、テーブルを削除します。
注釈
外部カタログとして AWS Glue データカタログを使用している場合、Snowflakeを介して外部管理テーブルを削除しても、基になるテーブルファイルは削除されません。この動作は、AWS Glueデータカタログ実装に固有のものです。
外部管理Icebergテーブルへの書き込み¶
外部管理Icebergテーブルでは、次の DML コマンドを使用できます。
/sql-reference/sql/copy-into-table`詳細については、 :doc:/user-guide/tables-iceberg-load` をご参照ください。
Snowpark API を使用してIcebergテーブルを処理することもできます。
例¶
次の基本的な例を使用して、Icebergテーブルへの書き込みを開始できます。
INSERT¶
INSERT を使用してIcebergテーブルに値を挿入します。
INSERT INTO my_iceberg_table VALUES (1, 'a');
INSERT INTO my_iceberg_table VALUES (2, 'b');
INSERT INTO my_iceberg_table VALUES (3, 'c');
UPDATE¶
UPDATE を使用してIcebergテーブルの値を更新します。
UPDATE my_iceberg_table
SET a = 10
WHERE b = 'b';
DELETE¶
DELETE を使用してIcebergテーブルから値を削除します。
DELETE my_iceberg_table
WHERE b = 'a';
MERGE¶
Icebergテーブルで MERGE を使用します。
MERGE INTO my_iceberg_table USING my_snowflake_table
ON my_iceberg_table.a = my_snowflake_table.a
WHEN MATCHED THEN
UPDATE SET my_iceberg_table.b = my_snowflake_table.b
WHEN NOT MATCHED THEN
INSERT VALUES (my_snowflake_table.a, my_snowflake_table.b);
COPY INTO <テーブル>¶
COPY INTO <テーブル> を使用してIcebergテーブルにデータをロードします。
COPY INTO customer_iceberg_ingest
FROM @my_parquet_stage
FILE_FORMAT = 'my_parquet_format'
LOAD_MODE = ADD_FILES_COPY
PURGE = TRUE
MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;
詳細については、Apache Iceberg™ テーブルへのデータのロード をご参照ください。
ストリームを使用した変更データキャプチャ¶
テーブルストリーム は、変更データキャプチャ(CDC)のソーステーブルの行に加えられた変更を追跡します。ソーステーブルは、標準のSnowflakeテーブル、Snowflake管理Icebergテーブル、または外部管理Icebergテーブルにすることができます。INSERT INTO… SELECT FROM… コマンドを使用して、外部管理のIcebergテーブルに変更を挿入できます。
注釈
ソーステーブルが外部管理Icebergテーブルの場合は、ストリームを作成するときに INSERT_ONLY = TRUE を使用する必要があります。
CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;
//...
INSERT INTO my_iceberg_table(id,name)
SELECT id, name
FROM my_stream;
Snowparkの使用¶
Snowpark Pythonを使用して、SnowflakeテーブルからIcebergテーブルにデータをコピーする関数を作成します。
def copy_into_iceberg():
try:
df = session.table("my_snowflake_table")
df.write.save_as_table("my_iceberg_table")
except Exception as e:
print(f"Error processing {table_name}: {e}")
トラブルシューティング¶
Snowflakeが外部カタログにテーブルの変更をコミットしようとしたときに問題が発生した場合、Snowflakeは次のエラーメッセージのいずれかを返します。
エラー |
004185=SQL Execution Error: Failed while committing transaction to external catalog. Error:''{0}''
または、 004185=SQL Execution Error: Failed while committing transaction to external catalog with unresolvable commit conflicts. Error:''{0}''
|
---|---|
原因 |
外部カタログへのコミットが失敗しました。 |
エラー |
004500=SQL Execution Error: Cannot verify the status of transaction from external catalog. The statement ''{0}'' with transaction id {1} may or may not have committed to external catalog. Error:''{2}''
|
---|---|
原因 |
外部カタログへのコミットに対し、外部カタログからの応答はありませんでした。メッセージには、外部カタログによって返された例外(利用可能な場合)が含まれます。利用できない場合は、Snowflakeが原因として |