ALTER ICEBERG TABLE¶
Ändert Eigenschaften wie Clustering-Optionen und Tags für eine bestehende Apache Iceberg™-Tabelle.
Sie können auch eine ALTER ICEBERG TABLE-Anweisung verwenden, um eine Tabelle zu aktualisieren, eine Tabelle zu konvertieren oder eine Spalte vom strukturierten Typ zu ändern. Die Syntax für diese Operationen ist sehr unterschiedlich. Syntax, Parameterbeschreibungen, Nutzungshinweise und Beispiele zum Aktualisieren oder Konvertieren einer Iceberg-Tabelle finden Sie auf den folgenden Seiten:
Unter diesem Thema werden Iceberg-Tabellen einfach als „Tabellen“ bezeichnet, es sei denn, die Angabe von Iceberg-Tabellen vermeidet Verwechslungen.
Syntax¶
ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction
ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
[ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
[ CATALOG_SYNC = '<open_catalog_integration_name>']
[ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
[ AUTO_REFRESH = { TRUE | FALSE } ]
ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> UNSET REPLACE_INVALID_CHARACTERS
ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction
Wobei:
clusteringAction ::= { CLUSTER BY ( <expr> [ , <expr> , ... ] ) /* { SUSPEND | RESUME } RECLUSTER is valid action */ | { SUSPEND | RESUME } RECLUSTER | DROP CLUSTERING KEY }dataGovnPolicyTagAction ::= { SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] | UNSET TAG <tag_name> [ , <tag_name> ... ] } | { ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] ) | DROP ROW ACCESS POLICY <policy_name> | DROP ROW ACCESS POLICY <policy_name> , ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] ) | DROP ALL ROW ACCESS POLICIES } | { SET AGGREGATION POLICY <policy_name> [ FORCE ] | UNSET AGGREGATION POLICY } | { { ALTER | MODIFY } [ COLUMN ] <col1_name> SET MASKING POLICY <policy_name> [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ] | UNSET MASKING POLICY } | { { ALTER | MODIFY } [ COLUMN ] <col1_name> SET PROJECTION POLICY <policy_name> [ FORCE ] | UNSET PROJECTION POLICY } | { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] , [ COLUMN ] <col2_name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] | { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ] , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Parameter¶
table_name
Bezeichner der zu ändernden Tabelle.
Wenn der Bezeichner Leerzeichen oder Sonderzeichen enthält, muss die gesamte Zeichenfolge in doppelte Anführungszeichen gesetzt werden. 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.
SET ...
Gibt eine oder mehrere Eigenschaften/Parameter an, die für die externe Tabelle festgelegt werden sollen (getrennt durch Leerzeichen, Kommas oder Neue-Zeile-Zeichen):
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
CATALOG_SYNC = 'snowflake_open_catalog_integration_name'
Gibt den Namen einer für Snowflake Open Catalog konfigurierten Katalogintegration an. Snowflake synchronisiert die Tabelle mit einem externen Katalog in Ihrem Snowflake Open Catalog-Konto. Weitere Informationen dazu finden Sie unter Eine Snowflake-verwaltete Tabelle mit Snowflake Open Catalog synchronisieren.
DATA_RETENTION_TIME_IN_DAYS = integer
Gibt die Aufbewahrungsfrist für eine Snowflake-verwaltete Tabelle an, sodass Time Travel-Aktionen (SELECT, CLONE, UNDROP) für historische Daten in der Tabelle durchgeführt werden können. Weitere Informationen dazu finden Sie unter Verstehen und Verwenden von Time Travel.
Eine ausführliche Beschreibung dieses Parameters auf Objektebene sowie weitere Informationen zu Objektparametern finden Sie unter Parameter.
Werte:
Standardausführung:
0
oder1
Enterprise Edition:
0
bis90
für permanente Tabellen
Standard:
Standardausführung:
1
Enterprise Edition (oder höher):
1
(es sei denn, es wurde ein anderer Standardwert auf Schema-, Datenbank- oder Kontoebene angegeben).
Bemerkung
Der Wert
0
deaktiviert Time Travel für die Tabelle.
AUTO_REFRESH = { TRUE | FALSE }
Gibt an, ob Snowflake den mit der Tabelle verbundenen externen Iceberg-Katalog automatisch nach Aktualisierungen der Metadaten abfragen soll, wenn Sie automatische Aktualisierung verwenden. Wenn für den Parameter
REFRESH_INTERVAL_SECONDS
bei der Katalogintegration kein Wert angegeben wird, verwendet Snowflake ein Standardaktualisierungsintervall von 30 Sekunden.Standard: FALSE
UNSET
Derzeit können Sie mit diesem Befehl nur den folgenden Parameter deaktivieren:
REPLACE_INVALID_CHARACTERS
Clustering-Aktionen (clusteringAction
)¶
Bemerkung
Clustering wird nur für Tabellen unterstützt, die Snowflake als Iceberg-Katalog verwenden.
CLUSTER BY ( expr [ , expr , ... ] )
Gibt eine oder mehrere Tabellenspalten oder Spaltenausdrücke als Gruppierungsschlüssel für die Tabelle an (oder ändert sie). Dies sind die Spalten/Ausdrücke, für die das Clustering mit Automatic Clustering verwaltet wird.
Mehr über Clustering erfahren Sie unter Gruppierungsschlüssel und geclusterte Tabellen.
SUSPEND | RESUME RECLUSTER
Aktiviert oder deaktiviert Automatic Clustering für die Tabelle.
DROP CLUSTERING KEY
Löscht den Gruppierungsschlüssel für die Tabelle.
Weitere Informationen zu Gruppierungsschlüsseln und Reclustering finden Sie unter Grundlegendes zu Tabellenstrukturen in Snowflake.
Data-Governance-Richtlinie und Tag-Aktionen (dataGovnPolicyTagAction
)¶
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.
policy_name
Bezeichner für die Richtlinie. Dieser muss für Ihr Konto eindeutig sein.
Die folgenden Klauseln gelten für alle Tabellentypen, die Zeilenzugriffsrichtlinien unterstützen, wie z. B. Tabellen, Ansichten und Ereignistabellen. Der Einfachheit halber wird in den Klauseln nur von „Tabelle“ gesprochen.
ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])
Fügt der Tabelle eine Zeilenzugriffsrichtlinie hinzu.
Es muss mindestens ein Spaltenname angegeben werden. Zusätzliche Spalten können mit einem Komma zwischen den einzelnen Spaltennamen angegeben werden. Verwenden Sie diesen Ausdruck, um eine Zeilenzugriffsrichtlinie sowohl zu einer Ereignistabelle als auch zu einer externen Tabelle hinzuzufügen.
DROP ROW ACCESS POLICY policy_name
Entfernt eine Zeilenzugriffsrichtlinie aus der Tabelle.
Verwenden Sie diese Klausel, um die Richtlinie in der Tabelle zu löschen.
DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )
Löscht mit nur einer einzigen SQL-Anweisung die für die Tabelle festgelegte Zeilenzugriffsrichtlinie und fügt eine Zeilenzugriffsrichtlinie zu derselben Tabelle hinzu.
DROP ALL ROW ACCESS POLICIES
Löscht alle Zuordnungen von Zeilenzugriffsrichtlinien aus der Tabelle.
Dieser Ausdruck ist hilfreich, wenn eine Zeilenzugriffsrichtlinie aus einem Schema gelöscht wird, bevor die Richtlinie aus einer Ereignistabelle gelöscht wird. Verwenden Sie diesen Ausdruck, um Zuordnungen von Zeilenzugriffsrichtlinien aus der Tabelle zu löschen.
SET AGGREGATION POLICY policy_name
[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]
Weist der Tabelle eine Aggregationsrichtlinie zu.
Verwenden Sie den optionalen Parameter ENTITY KEY, um festzulegen, welche Spalten eine Entität innerhalb der Tabelle eindeutig identifizieren. Weitere Informationen dazu finden Sie unter Implementieren von Datenschutz auf Entitätsebene mit Aggregationsrichtlinien.
Verwenden Sie den optionalen Parameter FORCE, um eine bestehende Aggregationsrichtlinie atomar durch die neue Aggregationsrichtlinie zu ersetzen.
UNSET AGGREGATION POLICY
Löst die Zuordnung einer Aggregationsrichtlinie zu der Tabelle auf.
{ ALTER | MODIFY } [ COLUMN ] ...
USING ( col_name , cond_col_1 ... )
Gibt die Argumente an, die an den SQL-Ausdruck für die bedingte Maskierungsrichtlinie übergeben werden sollen.
Die erste Spalte in der Liste gibt die Spalte für die Richtlinienbedingungen zur Maskierung oder Tokenisierung der Daten an. Sie muss mit der Spalte übereinstimmen, für die die Maskierungsrichtlinie festgelegt ist.
Die zusätzlichen Spalten geben an, welche Spalten ausgewertet werden sollen, um zu ermitteln, ob die Daten in der jeweiligen Zeile des Abfrageergebnisses maskiert oder tokenisiert werden sollen, wenn auf der ersten Spalte eine Abfrage ausgeführt wird.
Wenn die USING-Klausel weggelassen wird, behandelt Snowflake die bedingte Maskierungsrichtlinie wie eine normale Maskierungsrichtlinie.
FORCE
Ersetzt mit nur einer Anweisung eine Maskierungs- oder Projektionsrichtlinie, die derzeit für eine Spalte festgelegt ist, durch eine andere Richtlinie.
Beachten Sie, dass die Verwendung des Schlüsselworts
FORCE
mit einer Maskierungsrichtlinie voraussetzt, dass der Datentyp der Richtlinie in der ALTER TABLE-Anweisung (d. h. STRING) mit dem Datentyp der aktuell für die Spalte festgelegten Maskierungsrichtlinie (d. h. STRING) übereinstimmt.Wenn für die Spalte derzeit keine Maskierungsrichtlinie festgelegt ist, hat die Angabe dieses Schlüsselworts keine Auswirkungen.
Weitere Details dazu finden Sie unter Maskierungsrichtlinie auf einer Spalte ersetzen oder Projektionsrichtlinie ersetzen.
Anforderungen an die Zugriffssteuerung¶
Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:
Berechtigung |
Objekt |
Anmerkungen |
---|---|---|
OWNERSHIP |
Iceberg-Tabelle |
OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege). |
USAGE |
Externes Volume |
|
USAGE |
Katalogintegration |
Erforderlich, wenn die Tabelle eine Katalogintegration verwendet. |
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¶
Nur der Eigentümer der Tabelle (d. h. die Rolle mit der Berechtigung OWNERSHIP für die Tabelle) oder ein Benutzer mit weitreichenderen Berechtigungen kann diesen Befehl ausführen.
Clustering wird nur für Tabellen unterstützt, die Snowflake als Iceberg-Katalog verwenden. Für das Hinzufügen von Clustering zu einer Iceberg-Tabelle müssen Sie auch über USAGE- oder OWNERSHIP-Berechtigungen für das Schema und die Datenbank verfügen, die die Tabelle enthalten.
Sie können die Datenmetrikfunktionen mit Iceberg-Tabellen verwenden, indem Sie einen ALTER TABLE-Befehl ausführen. Weitere Informationen dazu finden Sie unter Verwenden von Datenmetrikfunktionen.
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.
Informationen zur Behebung von Problemen bei der Änderung des Parameters CATALOG_SYNC finden Sie unter Sie können eine Iceberg-Tabelle nicht ändern, wenn Sie den Parameter CATALOG_SYNC angeben
Beispiele¶
Das folgende Beispiel setzt ein Tag (my_tag
) mit dem Wert customer
auf eine Iceberg-Tabelle.
ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';