ALTER ICEBERG TABLE

Ändert die Eigenschaften, Spalten oder Einschränkungen für eine bestehende Iceberg-Tabelle. Wenn eine Iceberg-Tabelle eine Katalogintegration verwendet, verwenden Sie ALTER ICEBERG TABLE, um die Tabelle mit neuen Daten zu aktualisieren.

Sie können auch ALTER ICEBERG TABLE verwenden, um eine Tabelle, die eine Katalogintegration verwendet, in eine Tabelle umzuwandeln, die Snowflake als Iceberg-Katalog verwendet. Weitere Informationen dazu finden Sie unter Iceberg-Tabelle konvertieren.

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> REFRESH [ '<metadata_file_relative_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> CONVERT TO MANAGED [ BASE_LOCATION = '<file_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER ICEBERG TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Copy

Wobei:

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

Parameter

name

Bezeichner für die zu ändernde Iceberg-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.

REFRESH [ 'metadata_file_relative_path' ]

Greift für eine Iceberg-Tabelle, die nicht von Snowflake verwaltet wird, auf eine Metadatendatei unter dem angegebenen Pfad zu (relativ zum Speicherort des externen Volumes der Tabelle) und aktualisiert die Tabellenmetadaten.

Verwenden Sie diese Option nur, wenn Ihre Iceberg-Tabelle Iceberg-Dateien im Objektspeicher als Quelle verwendet. Lassen Sie diese Option weg, wenn Sie AWS Glue als Iceberg-Katalog verwenden.

Wenn beispielsweise s3://mybucket_us_east_1/metadata/v1.metadata.json der vollständige Pfad zu Ihrer Metadatendatei ist und der Speicherort für das externe Volume, das mit der Tabelle verbunden ist, s3://mybucket_us_east_1 lautet, geben Sie für metadata_file_relative_path den Wert metadata/v1.metadata.json an.

Bemerkung

Vor Snowflake-Version 7.34 war ein Parameter namens BASE_LOCATION (in früheren Versionen auch FILE_PATH genannt) erforderlich, um aus Iceberg-Dateien im Objektspeicher eine Tabelle zu erstellen. Der Parameter gab einen relativen Pfad vom EXTERNAL_VOLUME-Speicherort an.

Um eine Tabelle zu aktualisieren, die Sie mit der alten Syntax erstellt haben, geben Sie einen Pfad relativ zum BASE_LOCATION-Speicherort an. Wenn der vollständige Pfad zu Ihrer Metadatendatei beispielsweise s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json lautet, geben Sie für metadata-file-relative-path den Wert metadata/v1.metadata.json an.

CONVERT TO MANAGED

Konvertiert eine schreibgeschützte Iceberg-Tabelle, die eine Katalogintegration verwendet, in eine Tabelle, die Snowflake als Iceberg-Katalog verwendet. Die konvertierte Tabelle unterstützt sowohl Lese- als auch Schreiboperationen, und Snowflake übernimmt die gesamte Lebenszykluswartung der Tabelle, wie z. B. die Komprimierung. Weitere Informationen dazu finden Sie unter Iceberg-Tabelle konvertieren.

[ BASE_LOCATION = 'file_path' ]

Gibt einen relativen Pfad zu einem Verzeichnis vom EXTERNAL_VOLUME-Speicherort der Tabelle aus an, in das Snowflake Tabellendaten und Metadaten schreiben kann. Sie müssen bei der Konvertierung einen Wert für diese Eigenschaft angeben, wenn die ursprüngliche CREATE ICEBERG TABLE-Anweisung kein BASE_LOCATION zuließ oder einschloss.

Der Wert dieses Parameters kann nach der Konvertierung einer Tabelle nicht mehr geändert werden.

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

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.

UNSET

Derzeit können Sie mit diesem Befehl nur Folgendes aufheben:

  • TAG tag_name [ , tag_name ... ]

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.

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

Erforderlich für das manuelle Aktualisieren der Metadaten der Tabelle.

USAGE

Dateiformat

Erforderlich für das manuelle Aktualisieren der Metadaten der Tabelle.

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.

  • Die Verwendung des Befehls ALTER ICEBERG TABLE … REFRESH in Transaktionen (implizit oder explizit) wird nicht unterstützt.

  • Vor Snowflake-Version 7.34 war ein Parameter namens BASE_LOCATION (in früheren Versionen auch FILE_PATH genannt) erforderlich, um aus Iceberg-Dateien im Objektspeicher eine Tabelle zu erstellen. Der Parameter gab einen relativen Pfad vom EXTERNAL_VOLUME-Speicherort an.

    Um eine Tabelle zu aktualisieren, die Sie mit der alten Syntax erstellt haben, geben Sie einen Pfad relativ zum BASE_LOCATION-Speicherort an. Wenn der vollständige Pfad zu Ihrer Metadatendatei beispielsweise s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json lautet, geben Sie für metadata-file-relative-path den Wert metadata/v1.metadata.json an.

  • 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

Manuelles Aktualisieren von Tabellenmetadaten für Tabellen, die eine Katalogintegration verwenden

Iceberg-Dateien im Objektspeicher

In diesem Beispiel werden die Metadaten der Tabelle auf der Grundlage von Änderungen in einer neuen Metadatendatei manuell aktualisiert. In diesem Beispiel lautet der vollständige Pfad zur Metadatendatei <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json.

Bemerkung

Vor Snowflake-Version 7.34 war ein Parameter namens BASE_LOCATION (in früheren Versionen auch FILE_PATH genannt) erforderlich, um aus Iceberg-Dateien im Objektspeicher eine Tabelle zu erstellen. Der Parameter gab einen relativen Pfad vom EXTERNAL_VOLUME-Speicherort an.

Um eine Tabelle zu aktualisieren, die Sie mit der alten Syntax erstellt haben, geben Sie einen Pfad relativ zum BASE_LOCATION-Speicherort an. Wenn der vollständige Pfad zu Ihrer Metadatendatei beispielsweise s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json lautet, geben Sie für metadata-file-relative-path den Wert metadata/v1.metadata.json an.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';
Copy

AWS Glue

In diesem Beispiel werden die Metadaten einer Tabelle, die AWS Glue für den Iceberg-Katalog verwendet, manuell aktualisiert. Wenn Sie AWS Glue als Iceberg-Katalog verwenden, geben Sie im Aktualisierungsbefehl keinen Pfad zu einer Metadatendatei an.

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

Iceberg-Tabelle konvertieren

Im folgenden Beispiel wird die Anweisung ALTER ICEBERG TABLE … CONVERT TO MANAGED verwendet, um eine Tabelle, die nicht von Snowflake verwaltet wird, in eine Tabelle zu konvertieren, die Snowflake als Iceberg-Katalog verwendet.

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;
Copy