CREATE ICEBERG TABLE (Iceberg REST Katalog)¶
Erzeugt oder ersetzt eine Apache Iceberg™ Tabelle im aktuellen/vorgegebenen Schema für einen Iceberg REST-Katalog.
Verwenden Sie diesen Befehl für die folgenden Szenarios:
Sie möchten einen Remote-Iceberg-Katalog verwenden, der der Open Source Apache Iceberg REST OpenAPI–Spezifikation entspricht.
Sie möchten eine Tabelle in Snowflake Open Catalog oder Apache Polaris™ abfragen. Weitere Informationen dazu finden Sie unter Abfrage einer Tabelle in Snowflake Open Catalog mit Snowflake.
Sie möchten eine extern verwaltete Tabelle mit Schreibunterstützung in einer katalogverknüpften Datenbank erstellen. Siehe CREATE ICEBERG TABLE (katalogverknüpfte Datenbank).
Bemerkung
Bevor Sie eine Tabelle erstellen, müssen Sie das externe Volume erstellen, auf dem die Iceberg-Metadaten und -Datendateien gespeichert werden. Eine Anleitung dazu finden Sie unter Externes Volume konfigurieren.
Sie benötigen auch eine Katalogintegration für die Tabelle. Weitere Informationen dazu finden Sie unter Konfigurieren Sie eine Katalogintegration für Apache Iceberg™ REST-Kataloge oder Katalogintegration für Snowflake Open Catalog.
- Siehe auch:
ALTER ICEBERG TABLE, DROP ICEBERG TABLE, SHOW ICEBERG TABLES, DESCRIBE ICEBERG TABLE, UNDROP ICEBERG TABLE
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>' ]
[ 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> ... ] ) ]
Syntaxvariante¶
CREATE ICEBERG TABLE (katalogverknüpfte Datenbank)¶
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>' , ... ] ) ]
CREATE ICEBERG TABLE (katalogverknüpfte Datenbank) … AS SELECT¶
CREATE ICEBERG TABLE <table_name> [ ( <col_name> [ <col_type> ] , <col_name> [ <col_type> ] , ... ) ] [ ... ] AS SELECT <query>
Sie können eine Maskierungsrichtlinie auf eine Spalte in einer CTAS-Anweisung anwenden. Geben Sie die Maskierungsrichtlinie nach dem Datentyp der Spalte an. Beispiel:
CREATE ICEBERG TABLE <table_name> ( <col1> <data_type> [ WITH ] MASKING POLICY <policy_name> [ , ... ] ) [ ... ] AS SELECT <query>
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:
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¶
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:
TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'
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.
Anforderungen an die Zugriffssteuerung¶
Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:
Berechtigung |
Objekt |
Anmerkungen |
---|---|---|
CREATE ICEBERG TABLE |
Schema |
|
CREATE EXTERNAL VOLUME |
Konto |
Erforderlich, um ein neues externes Volume zu erstellen. |
USAGE |
Externes Volume |
Erforderlich, um auf ein vorhandenes externes Volume zu verweisen. |
CREATE INTEGRATION |
Konto |
Erforderlich, um eine neuen Katalogintegration zu erstellen. |
USAGE |
Katalogintegration |
Erforderlich, um auf eine bestehende Katalogintegration zu verweisen. |
USAGE-Berechtigung für die übergeordnete Datenbank und das Schema ist erforderlich, um Operationen an einem beliebigen Objekt in einem Schema durchzuführen.
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
- undIF 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.
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¶
Iceberg-Tabelle erstellen, die einen Remote-Iceberg-REST-Katalog verwendet¶
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;
Iceberg-Tabelle zur Abfrage einer Tabelle in Snowflake Open Catalog erstellen¶
In diesem Beispiel wird eine Iceberg-Tabelle erstellt, die Sie für Abfrage einer Tabelle in Snowflake Open Catalog mit Snowflake verwenden können.
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;
Iceberg-Tabelle in einer katalogverknüpften Datenbank erstellen¶
Im folgenden Beispiel wird eine schreibfähige Iceberg-Tabelle in einer katalogverknüpften Datenbank mit Spaltendefinitionen erstellt.
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
);