ALTER 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 ] <table_name> SET
  TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

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

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 als FILE_PATH bezeichnet) erforderlich, um aus Iceberg-Dateien im Objektspeicher eine Tabelle zu erstellen. Der Parameter gab einen relativen Pfad vom EXTERNAL_VOLUME-Speicherort der Tabelle an.

Um eine Tabelle zu aktualisieren, die Sie mit der alten Syntax erstellt haben, geben Sie einen Pfad relativ zum BASE_LOCATION-Speicherort der Tabelle 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 ein Tag aufheben:

TAG tag_name [ , tag_name ... ]

Clustering-Aktionen (clusteringAction)¶

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:

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.

• 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 folgenden Befehle können in expliziten Transaktionen verwendet werden (mit BEGIN … COMMIT): ALTER ICEBERG TABLE ... REFRESH ['metadata_file_relative_pathname']

  Explizite Transaktionen können verwendet werden, um beim manuellen Ersetzen aktualisierter Dateien in den Metadaten der Tabelle einen konsistenten Status sicherzustellen.

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

  Um eine Tabelle zu aktualisieren, die Sie mit der alten Syntax erstellt haben, geben Sie einen Pfad relativ zum BASE_LOCATION-Speicherort der Tabelle 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.

• Regarding metadata:

  Achtung

  Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadatenfelder in Snowflake.

Beispiele¶

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

ALTER ICEBERG TABLE myIcebergTable REFRESH;

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;