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.

Siehe auch:

CREATE ICEBERG TABLE, DROP ICEBERG TABLE, SHOW ICEBERG TABLES, DESCRIBE ICEBERG TABLE

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
Copy

Wobei:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }
Copy
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> ... ]
Copy

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 oder 1

  • Enterprise Edition: 0 bis 90 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';
Copy