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>' ]
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;
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);
Google Cloud Storage
CREATE STAGE mystage
URL='gcs://load/files/'
STORAGE_INTEGRATION = my_storage_int
DIRECTORY = (ENABLE = TRUE);
Microsoft Azure
CREATE STAGE mystage
URL='azure://myaccount.blob.core.windows.net/load/files/'
STORAGE_INTEGRATION = my_storage_int
DIRECTORY = (ENABLE = TRUE);
Manuelles Aktualisieren von Verzeichnistabellen¶
Aktualisieren Sie die Metadaten in einer Verzeichnistabelle manuell mit dem Befehl ALTER STAGE.
Beispiel:
ALTER STAGE mystage REFRESH;
Abrufen von Datei-URLs aus Verzeichnistabellen¶
Abfrage einer Verzeichnistabelle:
SELECT * FROM DIRECTORY( @<stage_name> )
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>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
einprivatelink
-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);
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;
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';
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.