CREATE ICEBERG TABLE (Iceberg REST Katalog)¶

Syntax¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<rest_catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Wobei:

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

Syntaxvariante¶

CREATE ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [
    --Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]
  ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

Erforderliche Parameter¶

table_name

Gibt den Bezeichner (Name) für die Tabelle in Snowflake an; 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.

Bemerkung

Um eine Liste von Tabellen oder Namespaces in Ihrem Remote-Katalog abzurufen, können Sie die folgenden Funktionen verwenden:

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

Gibt den Tabellennamen an, wie er von Ihrem externen Katalog erkannt wird. Dieser Parameter kann nicht mehr geändert werden, nachdem Sie die Tabelle erstellt haben.

Bemerkung

Geben Sie keinen Namespace mit dem Tabellennamen an (mynamespace.mytable). Um einen Namespace für diese Tabelle anzugeben und den Standard-Namespace für die Katalogintegration zu überschreiben setzen, verwenden Sie den Parameter CATALOG_NAMESPACE.

col_name

Zum Erstellen einer Tabelle in einer katalogverknüpften Datenbank (Vorschau).

Gibt den Spaltenbezeichner (Name) an. Alle Anforderungen an Tabellenbezeichner gelten auch für Spaltenbezeichner.

Weitere Informationen dazu finden Sie unter Anforderungen an Bezeichner und Reservierte und beschränkte Schlüsselwörter.

Bemerkung

Zusätzlich zu den standardmäßig reservierten Schlüsselwörtern können die folgenden Schlüsselwörter nicht als Spaltenbezeichner verwendet werden, da sie für Kontextfunktionen nach ANSI-Standard reserviert sind:

• CURRENT_DATE

• CURRENT_ROLE

• CURRENT_TIME

• CURRENT_TIMESTAMP

• CURRENT_USER

Die Liste der reservierten Schlüsselwörter finden Sie unter Reservierte und beschränkte Schlüsselwörter.

col_type

Zum Erstellen einer Tabelle in einer katalogverknüpften Datenbank (Vorschau).

Gibt den Datentyp für die Spalte an.

Weitere Informationen zu den Datentypen, die für Tabellenspalten angegeben werden können, finden Sie unter Datentypen für Apache Iceberg™-Tabellen.

Optionale Parameter¶

PARTITION BY = ( partitionExpression [ , partitionExpression , ... ] )

Gibt einen oder mehrere Partitionsausdrücke an.

MASKING POLICY = policy_name

Zum Erstellen einer Tabelle in einer katalogverknüpften Datenbank (Vorschau).

Gibt die Maskierungsrichtlinie an, die für eine Spalte festgelegt werden soll. Die Maskierungsrichtlinie muss zu einer Standard-Snowflake-Datenbank gehören (nicht zur katalogverknüpften Datenbank).

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 Sie diesen Parameter nicht angeben, wird in der Iceberg-Tabelle standardmäßig die Katalogintegration für das Schema, die Datenbank oder das Konto verwendet. Das Schema hat Vorrang vor der Datenbank, und die Datenbank hat Vorrang vor dem Konto.

CATALOG_NAMESPACE = 'catalog_namespace'

• Gibt optional den Namespace (z. B. my_database) für die REST-Katalogquelle an. Indem Sie einen Namespace bei der Katalogintegration und dann auf Tabellenebene angeben, können Sie eine einzige REST-Katalogintegration verwenden, um Iceberg-Tabellen in verschiedenen Datenbanken zu erstellen. Wenn Sie bei der Tabelle keinen Namespace angeben, verwendet die Tabelle den Standard-Namespace des Katalogs, der mit der Katalogintegration verbunden ist.

• Wenn bei der Katalogintegration kein Standard-Namespace angegeben wurde, müssen Sie den Namespace für die REST-Katalogquelle angeben, um einen Katalog-Namespace für die Tabelle festzulegen.

Bemerkung

Um eine Liste von Tabellen oder Namespaces in Ihrem Remote-Katalog abzurufen, können Sie die folgenden Funktionen verwenden:

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

Vorschau-Feature – Offen

Verfügbar bei allen Konten.

Gibt eine Zielgröße der Parquet-Datei für die Tabelle an.

• '{ 16MB | 32MB | 64MB | 128MB }' gibt eine feste Zieldateigröße für die Tabelle an.

• 'AUTO' funktioniert je nach Tabellentyp unterschiedlich:

  • Snowflake-verwaltete Tabellen: AUTO gibt an, dass Snowflake die Dateigröße für die Tabelle auf Grundlage von Tabellenmerkmalen wie Größe, DML-Muster, Datenaufnahme-Workload und Clustering-Konfiguration wählen soll. Snowflake passt die Dateigröße automatisch an, beginnend mit 16 MB, um die Leistung beim Lesen und Schreiben in Snowflake zu verbessern. Verwenden Sie diese Option, um die Tabellenleistung in Snowflake zu optimieren.

  • Extern verwaltete Tabellen: AUTO gibt an, dass Snowflake aggressiv auf die größte Dateigröße skalieren soll (128 MB).

Weitere Informationen dazu finden Sie unter Zieldateigröße festlegen.

Standard: AUTO

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Objektparameter, der die maximale Anzahl von Tagen angibt, für die Snowflake die Datenaufbewahrungsfrist für die Tabelle verlängern kann, um zu verhindern, dass Streams auf der Tabelle veraltet sind.

Eine detaillierte Beschreibung dieses Parameters finden Sie unter MAX_DATA_EXTENSION_TIME_IN_DAYS.

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

AUTO_REFRESH = { TRUE | FALSE }

Gibt an, ob Snowflake den mit der Tabelle verbundenen externen Iceberg-Katalog automatisch nach Aktualisierungen der Metadaten abfragen soll.

Wenn für den Parameter REFRESH_INTERVAL_SECONDS bei der Katalogintegration kein Wert angegeben wird, verwendet Snowflake ein Standardaktualisierungsintervall von 30 Sekunden.

Weitere Informationen dazu finden Sie unter Automatische Aktualisierung.

Standard: FALSE

Bemerkung

Verwendung von AUTO_REFRESH durch INFER_SCHEMA wird nicht unterstützt.

COPY GRANTS

Gibt an, dass die Zugriffsberechtigungen aus der Originaltabelle beibehalten werden, wenn eine neue Tabelle mit einer der folgenden CREATE TABLE-Varianten erstellt wird:

• CREATE OR REPLACE TABLE

Der Parameter kopiert alle Berechtigungen, mit Ausnahme von OWNERSHIP, aus der bestehenden Tabelle in die neue Tabelle. Die neue Tabelle übernimmt keine zukünftigen Berechtigungen, die für den Objekttyp im Schema definiert werden. Standardmäßig ist die Rolle, die die Anweisung CREATE TABLE ausführt, Eigentümer der neuen Tabelle.

Wenn der Parameter nicht in der CREATE ICEBERG TABLE-Anweisung enthalten ist, übernimmt die neue Tabelle keine expliziten Zugriffsrechte für die ursprüngliche Tabelle, übernimmt aber alle zukünftigen Berechtigungszuweisungen, die für den Objekttyp in dem Schema definiert werden.

Hinweis:

• Mit Datenfreigabe:

  • Wenn die vorhandene Tabelle für ein anderes Konto freigegeben wurde, wird auch die Ersatztabelle freigegeben.

  • Wenn die vorhandene Tabelle mit Ihrem Konto als Datenkonsument geteilt wurde und der Zugriff auf andere Rollen im Konto weiter gewährt wurde (unter Verwendung von GRANT IMPORTED PRIVILEGES auf der übergeordneten Datenbank), wird auch der Zugriff auf die Ersatztabelle gewährt.

• Die SHOW GRANTS-Ausgabe für die Ersetzungstabelle listet den Berechtigungsempfänger für die kopierten Berechtigungen als Rolle auf, die die CREATE ICEBERG TABLE-Anweisung ausgeführt hat, mit dem aktuellen Zeitstempel für den Zeitpunkt, an dem die Anweisung ausgeführt wurde.

• Die Operation zum Kopieren von Berechtigungen erfolgt atomar im Befehl CREATE ICEBERG TABLE (d. h. innerhalb derselben Transaktion).

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-Kontingent für Objekte.

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

Verknüpfen Sie das neue Objekt mit einem oder mehreren Kontakten.

Parameter für Partitionsausdrücke (partitionExpression)¶

Weitere Informationen zur Partitionierung von Iceberg-Tabellen finden Sie unter Iceberg-Partitionierung.

col_name

Gibt den Bezeichner (Name) für die zu partitionierende Quellspalte an.

Gibt bei alleiniger Verwendung ohne eine Transformation wie YEAR eine Identitätstransformation für die Quellspalte an. Weitere Informationen finden Sie unter Identität.

BUCKET

Gibt eine Bucket-Transformation an. Weitere Informationen dazu finden Sie unter Details zur Bucket-Transformation.

num_buckets gibt die Anzahl der Buckets an, in die die Daten gruppiert werden sollen.

TRUNCATE

Gibt eine Abschneiden-Transformation an, die die Daten auf der Grundlage der abgeschnittenen Werte der angegebenen Quellspalte partitioniert. Weitere Informationen dazu finden Sie unter Details zur Abschneiden-Transformation.

YEAR

Gibt eine Jahrestransformation an, die das Jahr aus einem Datums- oder Zeitstempelwert einer Quellspalte extrahiert. Weitere Informationen dazu finden Sie unter Partitionstransformationen.

MONTH

Gibt eine Monatstransformation an. Weitere Informationen dazu finden Sie unter Partitionstransformationen.

DAY

Gibt eine Tagestransformation an, die den Tag aus einem Datums- oder Zeitstempelwert einer Quellspalte extrahiert. Weitere Informationen dazu finden Sie unter Partitionstransformationen.

HOUR

Gibt eine Stundentransformation an, die die Stunde aus einem Zeitstempelwert einer Quellspalte extrahiert. Weitere Informationen dazu finden Sie unter Partitionstransformationen.

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:

USAGE-Berechtigung für die übergeordnete Datenbank und das Schema ist erforderlich, um Operationen an einem beliebigen Objekt in einem Schema durchzuführen. Beachten Sie, dass eine Rolle, die eine beliebige Berechtigung für ein Schema erhalten hat, es dieser Rolle erlaubt, das Schema aufzulösen. Zum Beispiel kann eine Rolle, der die CREATE-Berechtigung für ein Schema gewährt wurde, Objekte in diesem Schema erstellen, ohne auch USAGE für dieses Schema gewährt bekommen zu haben.

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¶

• 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.

• Zum Erstellen einer Iceberg-Tabelle mit Schreibunterstützung (Vorschau):

  • Wenn Sie eine Standard-Snowflake-Datenbank verwenden, müssen Sie zunächst eine Iceberg-Tabelle in Ihrem Remote-Katalog erstellen. Sie könnten zum Beispiel Spark verwenden, um eine Iceberg-Tabelle in Open Catalog zu schreiben. Geben Sie in Ihrer CREATE ICEBERG TABLE-Anweisung keine Spaltendefinitionen an.

  • Wenn Sie eine katalogverknüpfte Datenbank verwenden, müssen Sie beim Erstellen der Tabelle Spaltendefinitionen angeben. Alternativ können Sie auch in Iceberg-Tabellen schreiben, die Snowflake automatisch in Ihrem Remote-Katalog erkennt.

• Die TARGET_FILE_SIZE-Eigenschaft wird nur für Tabellen mit Schreibunterstützung (Vorschau) unterstützt.

• 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.

  • Die OR REPLACE- und IF NOT EXISTS-Klauseln schließen sich gegenseitig aus. Sie können nicht beide in derselben Anweisung verwendet werden.

  • Ä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.

• Syntaxvarianten verwenden:

  • CREATE ICEBERG TABLE … LIKE:

    • Für partitionierte Iceberg-Tabellen wird die Partitionierung der Quelltabelle ignoriert. Um dieses Verhalten zu überschreiben, geben Sie die PARTITION BY-Klausel mit dem Befehl an.

  • CREATE ICEBERG TABLE … CLONE:

    • Für partitionierte Iceberg-Tabellen behält die geklonte Tabelle die Partitionierungsdaten der Quelltabelle bei.

• Metadaten:

  Achtung

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

Beispiele¶

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

CREATE ICEBERG TABLE open_catalog_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'open_catalog_int'
  CATALOG_TABLE_NAME = 'my_open_catalog_table'
  AUTO_REFRESH = TRUE;

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

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE iceberg_partitioned_date_time (start_date timestamp)
  PARTITION BY (DAY(start_date));

INSERT INTO iceberg_partitioned_date_time (start_date)
  VALUES
    (to_timestamp_ntz('2023-01-02 00:00:00')),
    (to_timestamp_ntz('2023-02-03 00:00:00')),
    (to_timestamp_ntz('2023-01-02 01:00:00')),
    (to_timestamp_ntz('2023-02-03 02:00:00'));