Schreibunterstützung für extern verwaltete Apache Iceberg™-Tabellen¶

Hinweise¶

Beachten Sie Folgendes, wenn Sie Schreibunterstützung für extern verwaltete Iceberg-Tabellen verwenden:

• Snowflake bietet DDL (Data Definition Language)- und DML (Data Manipulation Language)-Befehle für extern verwaltete Tabellen. Sie konfigurieren jedoch Metadaten und die Datenaufbewahrung mit Ihrem externen Katalog und den Tools, die Ihr externer Speicheranbieter bereitstellt. Weitere Informationen dazu finden Sie unter Tabellen, die einen externen Katalog verwenden.

  Bei Schreibvorgängen stellt Snowflake sicher, dass Änderungen in Ihren Remote-Katalog übertragen werden, bevor die Tabelle in Snowflake aktualisiert werden.

• Wenn Sie eine mit einem Katalog verknüpfte Datenbank verwenden, können Sie die CREATE ICEBERG TABLE-Syntax mit Spaltendefinitionen verwenden, um eine Tabelle in Snowflake und in Ihrem Remote-Katalog zu erstellen. Wenn Sie eine Standard-Snowflake-Datenbank verwenden (nicht mit einem Katalog verknüpft), müssen Sie zunächst eine Tabelle in Ihrem Remote-Katalog erstellen. Danach können Sie die CREATE ICEBERG TABLE (Iceberg REST Katalog)-Syntax verwenden, um eine Iceberg-Tabelle in Snowflake zu erstellen und zu schreiben.

• Für den AWS Glue-Datenkatalog: Wenn Sie eine extern verwaltete Tabelle über Snowflake löschen, werden die zugrunde liegenden Tabellendateien nicht gelöscht. Dieses Verhalten ist spezifisch für die AWS Glue Data Catalog-Implementierung.

• Wenn Sie an der privaten Vorschau dieses Features teilgenommen haben, ist das Löschen von Positionszeilen in Ihrem Konto möglicherweise standardmäßig aktiviert. Führen Sie zur Überprüfung den folgenden Befehl aus:

  SHOW PARAMETERS LIKE 'ENABLE_ICEBERG_MERGE_ON_READ' IN ACCOUNT;
  

  Copy

  Wenn der Parameter in Ihrem Konto sichtbar ist (unabhängig von seinem Wert), sind Positionslöschungen aktiviert. Um das Löschen von Positionen zu deaktivieren, stellen Sie den ENABLE_ICEBERG_MERGE_ON_READ-Parameter auf Tabellen-, Schema- oder Datenbankebene auf FALSE ein.

• Das Schreiben in extern verwaltete Tabellen mit den folgenden Iceberg-Datentypen wird nicht unterstützt:

  • uuid

  • fixed(L)

• Die folgenden Features werden derzeit nicht unterstützt, wenn Sie Snowflake verwenden, um in extern verwaltete Iceberg-Tabellen zu schreiben:

  • Anmeldeinformationen über den Katalog.

  • Serverseitige Verschlüsselung (SSE) für GCS oder externe Azure-Volumes.

  • Transaktionen mit mehreren Anweisungen. Snowflake unterstützt nur Autocommit-Transaktionen.

  • Konvertierung in von Snowflake verwaltete Tabellen.

  • Externe Iceberg-Kataloge, die nicht mit dem Iceberg-REST-Protokoll übereinstimmen.

  • Löschungen auf Zeilenebene (merge-on-read).

  • Verwenden der OR REPLACE-Option beim Erstellen einer Tabelle.

  • Verwenden der CREATE TABLE … AS SELECT-Syntax, wenn Sie AWS Glue als Ihren Remote-Katalog verwenden.

• Beim Erstellen von Schemas in einer mit dem Katalog verbundenen Datenbank müssen Sie Folgendes beachten:

  • Der Befehl CREATE SCHEMA erstellt nur dann einen entsprechenden Namespace in Ihrem Remote-Katalog, wenn Sie eine mit dem Katalog verknüpfte Datenbank verwenden.

  • Die Optionen ALTER und CLONE werden nicht unterstützt.

  • Trennzeichen werden für Schemanamen nicht unterstützt. Es werden nur alphanumerische Schemanamen unterstützt.

• Sie können eine Zieldateigröße für die Parquet-Dateien einer Tabelle festlegen. Weitere Informationen dazu finden Sie unter Zieldateigröße festlegen.

Workflow¶

Verwenden Sie den in diesem Abschnitt beschriebenen Workflow, um mit diesem Feature zu beginnen:

1. Externes Volume konfigurieren

2. Katalogintegration erstellen

3. Sie können aus den folgenden Optionen wählen:

   • Eine mit dem Katalog verbundene Datenbank erstellen. Mit dieser Option können Sie in automatisch ermittelte Iceberg-Tabellen in Ihrem Katalog schreiben oder die mit dem Katalog verknüpfte Datenbank verwenden, um zusätzliche Iceberg-Tabellen zu erstellen.

   • Iceberg-Tabelle erstellen (in einer mit dem Katalog verknüpften Datenbank oder einer Standard-Snowflake-Datenbank). Mit dieser Option müssen Sie zunächst eine Tabelle in Ihrem Remote-Katalog erstellen, bevor Sie eine extern verwaltete Iceberg-Tabelle in Snowflake anlegen.

Nachdem Sie diese Schritte abgeschlossen haben, können Sie Schreiboperationen für Ihre Iceberg-Tabellen ausführen.

Konfigurieren eines externen Volumes für Schreibvorgänge auf extern verwaltete Tabellen¶

Um Schreibvorgänge auf extern verwaltete Tabellen zu ermöglichen, müssen Sie ein externes Volume verwenden, das sowohl mit Lese- als auch mit Schreibberechtigungen für den Snowflake-Dienstprinzipal konfiguriert ist (die gleichen Berechtigungen, die für von Snowflake verwaltete Tabellen erforderlich sind).

Geben Sie den Speicherort an (STORAGE_BASE_URL), wo der Iceberg REST-Katalog Iceberg-Daten und -Metadaten schreibt.

Die folgende Anweisung erstellt beispielsweise ein externes Volume für S3 mit Verschlüsselung, das Schreibzugriff auf einen Bucket namens my-iceberg-tables ermöglicht:

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;

Umfassende Anleitungen finden Sie unter den folgenden Themen:

• Externes Volume für Amazon S3 konfigurieren

• Externes Volume für Google Cloud Storage konfigurieren

• Externes Volume für Azure Storage konfigurieren

Weitere Informationen zu den erforderlichen Berechtigungen finden Sie unter Snowflake Zugriff auf Ihren Speicher erteilen.

Konfigurieren einer Katalogintegration¶

Für das Schreiben in extern verwaltete Iceberg-Tabellen müssen Sie eine Katalogintegration konfigurieren, um Snowflake mit Ihrem Remote-Katalog zu verbinden.

Ihr Remote-Katalog muss der Open Source Apache Iceberg REST OpenAPI-Spezifikation entsprechen, wie z. B. Open Catalog oder dem AWS Glue Iceberg REST-Katalog.

Informationen zum Erstellen einer Katalogintegration finden Sie in den Anweisungen unter den folgenden Themen:

• Konfigurieren Sie eine Katalogintegration für AWS Glue Iceberg REST. Verwenden Sie die Berechtigungen in der IAM-Beispielrichtlinie für Lesen und Schreiben.

  Bemerkung

  Wenn Sie derzeit eine :doc:`Katalogintegration für AWS Glue </user-guide/tables-iceberg-configure-catalog-integration-glue>`verwenden, müssen Sie eine neue REST-Katalogintegration für den AWS Glue Iceberg REST-Endpunkt erstellen.

• Katalogintegration für Snowflake Open Catalog

• Konfigurieren Sie eine Katalogintegration für Apache Iceberg™ REST-Kataloge

Eine mit dem Katalog verbundene Datenbank erstellen¶

Snowflake unterstützt das Erstellen von schreibbaren, extern verwalteten Tabellen in einer katalogverknüpften Datenbank, d. h. einer Snowflake-Datenbank, die Sie mit einem externen Iceberg REST-Katalog synchronisieren. Sie können auch in Iceberg-Tabellen schreiben, die Snowflake automatisch in Ihrem Remote-Katalog erkennt. Weitere Informationen dazu finden Sie unter Verwenden einer mit dem Katalog verbundene Datenbank für Apache Iceberg™-Tabellen.

Im folgenden Beispiel wird der Befehl CREATE DATABASE (katalogverknüpft) verwendet, um eine katalogverknüpfte Datenbank zu erstellen, die ein externes Volume verwendet:

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  ),
  EXTERNAL_VOLUME = 'my_external_vol';

CREATE SCHEMA 'my_namespace';

DROP SCHEMA 'my_namespace';

Iceberg-Tabelle erstellen¶

Das Erstellen einer extern verwalteten Iceberg-Tabelle, in die Sie von Snowflake aus schreiben können, hängt von der Art der verwendeten Datenbank ab:

• Wenn Sie eine katalogverknüpfte Datenbank verwenden, können Sie die CREATE ICEBERG TABLE (katalogverknüpfte Datenbank) verwenden, um eine Tabelle zu erstellen und sie in Ihrem Remote-Katalog zu registrieren. Eine Anweisung dazu finden Sie unter Iceberg-Tabelle in einer katalogverknüpften Datenbank erstellen.

• Wenn Sie eine Standard-Snowflake-Datenbank verwenden (nicht mit einem Katalog verknüpft), müssen Sie zunächst eine Tabelle in Ihrem Remote-Katalog erstellen. Dann können Sie die CREATE ICEBERG TABLE (Iceberg REST Katalog)-Syntax verwenden, um eine Iceberg-Tabelle in Snowflake zu erstellen und zu schreiben. Eine Anweisung dazu finden Sie unter Erstellen einer Iceberg-Tabelle in einer Standard-Snowflake-Datenbank.

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

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

Löschen einer Iceberg-Tabelle¶

Sie können gleichzeitig eine schreibbare, extern verwaltete Iceberg-Tabelle aus Snowflake und aus Ihrem Remote-Katalog löschen, indem Sie den Befehl DROP ICEBERG TABLE verwenden.

DROP ICEBERG TABLE my_iceberg_table;

Snowflake löscht die Tabelle und ruft auch Ihren externen Iceberg-Katalog auf, um ihn anzuweisen, die Tabelle zu löschen und die zugrunde liegenden Daten und Metadaten der Tabelle zu löschen.

Snowflake löscht die Tabelle erst, wenn bestätigt wurde, dass die Tabelle erfolgreich aus dem Remote-Katalog gelöscht wurde.

Schreiben in extern verwaltete Iceberg-Tabellen¶

Sie können die folgenden DML-Befehle für extern verwaltete Iceberg-Tabellen verwenden:

• INSERT

  • Beispiel: Mehrzeiliges Einfügen mit einer Abfrage (INSERT INTO … SELECTFROM)

  • Beispiel: INSERT INTO … SELECT FROM (Stream)

• UPDATE

• DELETE

• MERGE

• TRUNCATE TABLE

• COPY INTO <Tabelle>. Weitere Informationen dazu finden Sie unter Laden von Daten in Apache Iceberg™-Tabellen.

Sie können auch den Snowpark API verwenden, um Iceberg-Tabellen zu verarbeiten.

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 my_iceberg_table
  SET a = 10
  WHERE b = 'b';

DELETE my_iceberg_table
  WHERE b = 'a';

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

CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;

//...

INSERT INTO my_iceberg_table(id,name)
  SELECT id, name
  FROM my_stream;

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}")

Problembehandlung¶

Falls ein Problem auftritt, wenn Snowflake versucht, Tabellenänderungen in Ihren externen Katalog zu übertragen, gibt Snowflake eine der folgenden Fehlermeldungen zurück.

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