Verwalten von Verzeichnistabellen

Unter diesem Thema wird eine Anleitung zum Erstellen und Verwalten externer oder interner Stagingbereiche mittels Verzeichnistabellen bereitgestellt.

Unter diesem Thema:

Automatisches Aktualisieren der Metadaten in Verzeichnistabellen

Die Metadaten von Verzeichnistabellen können automatisch über den Ereignisbenachrichtigungsdienst Ihres Cloudspeicherdienstes aktualisiert werden.

Bei Aktualisierungsoperationen werden die Metadaten mit dem neuesten Satz zugeordneter Dateien im externen Stagingbereich und Pfad synchronisiert, d. h.:

  • Neue Dateien im Pfad werden zu den Tabellenmetadaten hinzugefügt.

  • Änderungen an Dateien im Pfad werden in den Tabellenmetadaten aktualisiert.

  • Dateien, die sich nicht mehr im Pfad befinden, werden aus den Tabellenmetadaten entfernt.

Eine Anleitung zum Erstellen von Stagingbereichen mit automatisch aktualisierten Verzeichnistabellen finden Sie unter Automatisiertes Aktualisieren der Metadaten von Verzeichnistabellen.

Bemerkung

Das automatische Aktualisieren der Metadaten von Verzeichnistabellen interner Stagingbereiche, die auf externe Cloudspeicher verweisen, ist nicht möglich. Für diese Typen von Stagingbereichen müssen Sie die Metadaten der Verzeichnistabelle manuell aktualisieren. Eine Anleitung dazu finden Sie unter Manuelles Aktualisieren der Metadaten von Verzeichnistabellen (unter diesem Thema).

Wir empfehlen Ihnen, unsere Best Practices für das Staging Ihrer Datendateien zu befolgen und regelmäßig eine ALTER STAGE … REFRESH-Anweisung auszuführen, um fehlende Dateien zu registrieren. Für eine zufriedenstellende Leistung empfehlen wir außerdem die Verwendung eines selektiven Pfadpräfixes mit ALTER STAGE. Dadurch wird die Anzahl der Dateien reduziert, die aufgelistet und daraufhin geprüft werden müssen, ob sie bereits registriert wurden (z. B. bucket_name/YYYY/MM/DD/ oder auch bucket_name/YYYY/MM/DD/HH/, abhängig vom Volumen).

Manuelles Aktualisieren der Metadaten von Verzeichnistabellen

Dieser Abschnitt enthält eine Anleitung zum Erstellen von Stagingbereichen (unter Verwendung von CREATE STAGE), die über eine Verzeichnistabelle zum Speichern von Metadaten über die Stagingdateien verfügen. Die mithilfe der Anleitung erstellten Verzeichnistabellen erfordern eine manuelle Aktualisierung der Metadaten.

Gegenwärtig müssen die Metadaten der Verzeichnistabellen von internen Stagingbereichen manuell aktualisiert werden. Sie können auch für externe Stagingbereiche eine Verzeichnistabelle erstellen und die Metadaten manuell aktualisieren. Weitere Informationen zum automatischen Aktualisieren von Metadaten finden Sie unter Automatisches Aktualisieren von Metadaten in Verzeichnistabellen (unter diesem Thema).

Bemerkung

Das manuelle Aktualisieren von Metadaten in einem externen Stagingbereich verhindert, dass zur gleichen Zeit automatisierte Aktualisierungsoperationen ausgeführt werden. Die automatischen Aktualisierungen werden nach Abschluss der manuellen Aktualisierung fortgesetzt.

Die Syntax für das Erstellen eines Stagingbereichs mit einer Verzeichnistabelle ist nahezu identisch mit dem Erstellen eines standardmäßigen externen oder internen Stagingbereichs. Setzen Sie den optionalen DIRECTORY-Parameter auf TRUE.

Die vollständige Syntax- und Parameterbeschreibung finden Sie unter CREATE STAGE.

Syntax

-- Internal stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <internal_stage_name>
  [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
  [ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]
  [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
  [ COPY_OPTIONS = ( copyOptions ) ]
  [ COMMENT = '<string_literal>' ]

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
      <cloud_storage_access_settings>
    [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]
Copy

Wobei:

ENABLE = TRUE | FALSE

Gibt an, ob eine Verzeichnistabelle zum Stagingbereich hinzugefügt werden soll. Wenn der Wert TRUE ist, wird beim Erstellen des Stagingbereichs auch eine Verzeichnistabelle erstellt.

Standard: FALSE

[ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

Gibt den Typ der Verschlüsselung an, der für alle im Stagingbereich gespeicherten Dateien unterstützt wird.

TYPE = ...

Gibt den verwendeten Verschlüsselungstyp an. Mögliche Werte sind:

  • SNOWFLAKE_FULL: Clientseitige Verschlüsselung. Die Dateien werden von einem Client verschlüsselt, wenn dieser sie mit PUT in den internen Stagingbereich hochlädt.

  • SNOWFLAKE_SSE: Serverseitige Verschlüsselung. Die Dateien sind verschlüsselt, wenn sie im Stagingbereich ankommen.

    Geben Sie die serverseitige Verschlüsselung an, wenn Sie für Ihre Stagingdateien vorsignierte URLs abfragen möchten.

    Wenn die Dateien in einem Stagingbereich clientseitig verschlüsselt sind, können Benutzer die Stagingdateien nur lesen, wenn sie Zugriff auf den Verschlüsselungsschlüssel haben.

    Weitere Informationen zu internen benannten Stagingbereichen mit ausschließlich serverseitiger Verschlüsselung finden Sie unter CREATE STAGE.

Standard: SNOWFLAKE_FULL

Nutzungshinweise

  • Nachdem Sie einen Stagingbereich mit einer Verzeichnistabelle erstellt haben, müssen Sie ALTER STAGE … REFRESH ausführen, um die Metadaten der Verzeichnistabelle manuell zu aktualisieren.

Beispiele

Erstellen Sie einen internen Stagingbereich namens mystage, der eine Verzeichnistabelle enthält. Der Stagingbereich verweist auf ein Dateiformat mit dem Namen myformat:

CREATE STAGE mystage
  DIRECTORY = (ENABLE = TRUE)
  FILE_FORMAT = myformat;
Copy

Erstellen Sie einen externen Stagingbereich namens mystage, die eine Verzeichnistabelle enthält. Der Stagingbereich verweist auf einen Bucket oder Container mit dem Namen load und dem Pfad files. Sicherer Zugriff auf den Cloudspeicherort wird über die Speicherintegration my_storage_int bereitgestellt:

Bemerkung

Der Speicherort im URL-Wert muss mit einem Schrägstrich (/) enden.

Amazon S3

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Google Cloud Storage

CREATE STAGE mystage
  URL='gcs://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Microsoft Azure

CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Manuelles Aktualisieren von Verzeichnistabellen

Aktualisieren Sie die Metadaten in einer Verzeichnistabelle manuell mit dem Befehl ALTER STAGE.

Beispiel:

ALTER STAGE mystage REFRESH;
Copy

Abrufen von Datei-URLs aus Verzeichnistabellen

Abfrage einer Verzeichnistabelle:

SELECT * FROM DIRECTORY( @<stage_name> )
Copy

Wobei:

stage_name

Name eines Stagingbereichs, der eine Verzeichnistabelle enthält.

Weitere Informationen zu SELECT als Anweisung und zu den anderen Klauseln in dieser Anweisung finden Sie unter Abfragesyntax.

Ausgabe

Die Ausgabe einer Verzeichnistabellenabfrage kann die folgenden Spalten enthalten:

Spalte

Datentyp

Beschreibung

RELATIVE_PATH

TEXT

Pfad zu den Dateien, auf die mit der Datei-URL zugegriffen werden soll.

SIZE

NUMBER

Größe der Datei (in Byte)

LAST_MODIFIED

TIMESTAMP_LTZ

Zeitstempel, wann die Datei im Stagingbereich zuletzt aktualisiert wurde

MD5

HEX

MD5-Prüfsumme für die Datei

ETAG

HEX

ETag-Header für die Datei

FILE_URL

TEXT

Snowflake-gehostete Datei-URL zu der Datei.

Die Datei-URL hat das folgende Format:

https://<account_identifier>/api/files/<db_name>.<schema_name>.<stage_name>/<relative_path>
Copy

Wobei:

account_identifier

Hostname des Snowflake-Kontos für Ihren Stagingbereich. Der Hostname beginnt mit einem eindeutigen Konto-Locator (von Snowflake bereitgestellt) und endet mit der Snowflake-Domain (snowflakecomputing.com):

account_locator.snowflakecomputing.com

Weitere Details dazu finden Sie unter Kontobezeichner.

Bemerkung

Für Business Critical-Konten wird der URL direkt vor snowflakecomputing.com ein privatelink-Segment vorangestellt (privatelink.snowflakecomputing.com), auch wenn private Konnektivität zum Snowflake-Dienst für Ihr Konto nicht aktiviert ist.

db_name

Name der Datenbank, die den Stagingbereich enthält, in dem sich Ihre Dateien befinden.

schema_name

Name des Schemas, das den Stagingbereich enthält, in dem sich Ihre Dateien befinden.

stage_name

Name des Stagingbereichs, in dem sich Ihre Dateien befinden.

relative_path

Pfad zu den Dateien, auf die mit der Datei-URL zugegriffen werden soll.

Nutzungshinweise

  • Wenn aus einem internen Stagingbereich heruntergeladene Dateien beschädigt sind, überprüfen Sie mit dem Ersteller des Stagingbereichs, ob ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE') für den Stagingbereich eingestellt ist.

Beispiele

Abrufen aller Metadatenspalten in der Verzeichnistabelle eines Stagingbereichs namens mystage:

SELECT * FROM DIRECTORY(@mystage);
Copy

Rückgabe der FILE_URL-Spaltenwerte aus der gleichen Verzeichnistabelle. Gibt die Datei-URLs nur für Dateien zurück, die größer als 100 KB sind:

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE SIZE > 100000;
Copy

Rückgabe der FILE_URL-Spaltenwerte aus der gleichen Verzeichnistabelle. Gibt nur die Datei-URLs für kommagetrennte Wertedateien zurück:

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE RELATIVE_PATH ILIKE '%.csv';
Copy

Streams auf Verzeichnistabellen

Mit Standardstreams (d. h. Delta-Streams) auf einer Verzeichnistabelle werden Dateien verfolgt, die am referenzierten Cloudspeicherort hinzugefügt oder gelöscht werden. Die Syntax diese SQL-Befehls und Beispiele finden Sie unter CREATE STREAM.