CREATE ICEBERG TABLE (Delta-Dateien im Objektspeicher)¶

Syntax¶

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

Erforderliche Parameter¶

table_name

Gibt den Bezeichner (den Namen) für die Tabelle an. Dieser muss für das Schema, in dem die Tabelle erstellt wird, eindeutig sein.

Darüber hinaus muss der Bezeichner mit einem Buchstaben beginnen und darf keine Leer- oder Sonderzeichen enthalten, es sei denn, die gesamte Bezeichnerzeichenfolge wird in doppelte Anführungszeichen gesetzt (z. B. "My object"). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß-/Kleinschreibung zu beachten.

Weitere Informationen dazu finden Sie unter Anforderungen an Bezeichner.

BASE_LOCATION = 'relative_path_from_external_volume'

Gibt einen relativen Pfad vom Speicherort der Tabelle EXTERNAL_VOLUME zu einem Verzeichnis an, in dem Snowflake auf Ihre Delta-Tabellendateien zugreifen kann.

Der Speicherort muss auf ein Verzeichnis verweisen und darf nicht auf eine einzelne Datei verweisen. Er muss den Unterordner für das Delta-Transaktionsprotokoll enthalten (z. B. my/base/location/_delta_log/).

Optionale Parameter¶

EXTERNAL_VOLUME = 'external_volume_name'

Gibt den Bezeichner (Name) für das externe Volume an, auf dem die Iceberg-Tabelle ihre Metadatendateien und die Daten im Parquet-Format speichert. In Iceberg-Metadaten- und Iceberg-Manifest-Dateien sind das Tabellenschema, die Partitionen, die Snapshots und andere Metadaten gespeichert.

Wenn Sie diesen Parameter nicht angeben, wird für die Iceberg-Tabelle standardmäßig das externe Volume von Schema, Datenbank oder Konto verwendet. Das Schema hat Vorrang vor der Datenbank, und die Datenbank hat Vorrang vor dem Konto.

CATALOG = 'catalog_integration_name'

Gibt den Bezeichner (Name) der Katalogintegration für diese Tabelle an.

Wenn nichts angegeben wird, ist die Iceberg-Tabelle standardmäßig die Katalogintegration für das Schema, die Datenbank oder das Konto. Das Schema hat Vorrang vor der Datenbank, und die Datenbank hat Vorrang vor dem Konto.

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

Gibt an, ob in Abfrageergebnissen ungültige UTF-8-Zeichen durch das Unicode-Ersetzungszeichen (�) ersetzt werden sollen. Sie können diesen Parameter nur für Tabellen festlegen, die einen externen Iceberg-Katalog verwenden.

• TRUE: Snowflake ersetzt ungültige UTF-8-Zeichen durch das Unicode-Ersetzungszeichen.

• FALSE lässt ungültige UTF-8-Zeichen unverändert. Snowflake gibt eine Fehlermeldung an den Benutzer zurück, wenn es auf ein ungültiges UTF-8-Zeichen in einer Parquet-Datendatei stößt.

Wenn nichts angegeben wird, ist die Iceberg-Tabelle standardmäßig die Katalogintegration für das Schema, die Datenbank oder das Konto. Das Schema hat Vorrang vor der Datenbank, und die Datenbank hat Vorrang vor dem Konto.

Standard: FALSE

COMMENT = 'string_literal'

Gibt einen Kommentar für die Tabelle an.

Standard: Kein Wert

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

Gibt den Namen des Tags und den Wert der Tag-Zeichenfolge an.

Der Tag-Wert ist immer eine Zeichenfolge, die maximale 256 Zeichen lang sein kann.

Weitere Informationen zur Angabe von Tags in einer Anweisung finden Sie unter Tag-Kontingente für Objekte und Spalten.

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Beachten Sie, dass für die Bearbeitung eines Objekts in einem Schema auch die Berechtigung USAGE für die übergeordnete Datenbank und das Schema erforderlich ist.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise¶

• Hinweise zur Ausführung dieses Befehls:

  • Wenn Sie Ihr externes Volume oder die Katalogintegration mit einem Bezeichner in doppelten Anführungszeichen erstellt haben, müssen Sie den Bezeichner genau so wie erstellt (einschließlich der doppelten Anführungszeichen) in Ihrer CREATE ICEBERG TABLE-Anweisung angeben. Fehlende Anführungszeichen können zu einem Object does not exist-Fehler (oder einer ähnlichen Art von Fehler) führen.

• Hinweise zu Iceberg-Tabellen, die aus Delta-Tabellen-Dateien erstellt wurden:

  • Sie können Time Travel verwenden, um Iceberg-Tabellen abzufragen, die aus Delta-Tabellendateien erstellt wurden. Die Tabellenversionen entsprechen den einzelnen Delta-Log-Commit-Dateien.

  • Iceberg-Tabellen sind mit Daten kompatibel, die mit Delta Lake Version 3.1 und früher erzeugt wurden.

  • Snowflake-Streams werden für Iceberg-Tabellen, die aus Delta-Tabellen-Dateien mit Partitionsspalten erstellt wurden, nicht unterstützt. Allerdings werden Nur-Einfügen-Streams für Tabellen, die aus Delta-Dateien ohne Partitionsspalten erstellt wurden, unterstützt.

  • Dynamische Tabellen werden bei Iceberg-Tabellen, die aus Delta-Tabellendateien erstellt wurden, nicht unterstützt.

  • Snowflake unterstützt die Erstellung von Iceberg-Tabellen aus Delta-Tabellendefinitionen im AWS Glue Data-Katalog nicht.

  • Parquet-Dateien (Datendateien für Delta-Tabellen), die eines der folgenden Features oder Datentypen verwenden, werden nicht unterstützt:

    • Feld-IDs

    • Der Datentyp INTERVAL.

    • Der Datentyp DECIMAL mit einer Präzision von mehr als 38.

    • LIST oder MAP-Typen mit ein- oder zweistufiger Darstellung.

    • Ganzzahl-Typen ohne Vorzeichen (INT(vorzeichenbehaftet = falsch)).

    • Der Datentyp FLOAT16.

    Weitere Informationen zu Delta-Datentypen und Iceberg-Tabellen finden Sie unter Delta-Datentypen.

  • Aktualisierungsoperationen während CREATE und ALTER … REFRESH können maximal 1.000 Delta-Commit-Dateien pro Operation verarbeiten.

    Bemerkung

    Snowflake verwendet bei der Erstellung einer Iceberg-Tabelle Delta-Checkpoint-Dateien. Die Beschränkung auf 1.000 Commit-Dateien gilt nur für Commits nach dem letzten Prüfpunkt.

  • Die Erzeugung von Iceberg-Metadaten mit der Funktion SYSTEM$GET_ICEBERG_TABLE_INFORMATION wird nicht unterstützt.

  • Die folgenden Funktionen von Delta Lake werden derzeit nicht unterstützt: Zeilenverfolgung, Löschvektordateien, Ändern von Datendateien, Ändern von Metadaten, DataChange, CDC, Protokollentwicklung.

• Hinweise zum Erstellen von Tabellen:

  • Ein Schema darf keine Tabellen und/oder Ansichten mit gleichem Namen enthalten. Beim Erstellen einer Tabelle:

    • Wenn im Schema bereits eine Ansicht mit dem gleichen Namen vorhanden ist, wird ein Fehler zurückgegeben und die Tabelle nicht erstellt.

    • Wenn bereits eine Tabelle mit dem gleichen Namen im Schema existiert, wird ein Fehler zurückgegeben, und die Tabelle wird nicht erstellt, es sei denn, das optionale Schlüsselwort OR REPLACE ist im Befehl enthalten.

  • CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

    Das bedeutet, dass alle Abfragen, die parallel zur Operation CREATE OR REPLACE ICEBERG TABLE ausgeführt werden, entweder die alte oder die neue Version der Tabelle verwenden.

  • Ähnlich wie bei reservierten Schlüsselwörtern können ANSI-reservierte Funktionsnamen (z. B. CURRENT_DATE, CURRENT_TIMESTAMP) nicht als Spaltennamen verwendet werden.

  • Wenn Sie eine Tabelle neu erstellen (mit dem optionalen Schlüsselwort OR REPLACE), wird deren Verlauf gelöscht, wodurch alle Streams auf der Tabelle veraltet sind. Ein veralteter Stream ist unlesbar.

• Metadaten:

  Achtung

  Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

Beispiele¶

Der folgende Beispielbefehl erstellt eine Iceberg-Tabelle aus Delta-Tabellendateien im Objektspeicher.

Im wird Beispiel ein externes Volume angegeben, das mit dem Cloud-Speicherort der Delta-Tabellendateien verbunden ist, eine Katalogintegration, die für Delta konfiguriert ist, und einen Wert für den erforderlichen Parameter BASE_LOCATION.

CREATE ICEBERG TABLE my_delta_iceberg_table
  CATALOG = delta_catalog_integration
  EXTERNAL_VOLUME = delta_external_volume
  BASE_LOCATION = 'relative/path/from/ext/vol/';

Wenn die Delta-Tabelle ein Partitionierungsschema verwendet, interpretiert Snowflake das Schema automatisch aus dem Delta-Protokoll.