COPY FILES¶
Dateien aus einem Stagingbereich in einen Ausgabebereich kopieren Sie können die zu kopierende Dateiliste mithilfe einer Abfrage oder eines Freigabeangebots in einem bestehenden Stagingbereich bereitstellen.
Verwenden Sie einen Stagingbereich als Quelle, wenn Sie Dateien kopieren möchten, für folgende Szenarien:
Zwischen Stagingbereichen ohne Umbenennung
Aus einer Reihe von Dateien, die auf einem einzigen Muster basieren, zwischen Stagingbereichen ohne Umbenennung
Aus einer Reihe von fest kodierten Dateinamen
Verwenden Sie eine Abfrage als Quelle, wenn Sie Dateien kopieren möchten, für folgende Szenarios:
Von oder zu einer Gruppe von Dateien, die durch eine Abfrage definiert sind (SELECT-Anweisung).
Aus Dateien, die von einer UDF (zum Beispiel Schreiben von Dateien aus Snowpark Python UDFs und UDTFs) geschrieben wurden.
Von eingeschränkten oder Stagingbereich-URLs.
Dieser Befehl unterstützt Dateikopieroperationen von und nach vorhandenen benannten Stagingbereichen, wie die folgende Tabelle veranschaulicht:
Quellspeicherort |
Zielspeicherort |
---|---|
Interner benannter Stagingbereich |
Interner benannter Stagingbereich |
Externer Stagingbereich |
Interner benannter Stagingbereich |
Interner benannter Stagingbereich |
Externer Stagingbereich |
Externer Stagingbereich |
Externer Stagingbereich |
Ein externer Ziel- oder Quell-Stagingbereich kann auf Dateien in einem der folgenden Cloudspeicherdienste oder an einem lokalen Speicherort verweisen:
Amazon S3
Google Cloud Storage
Microsoft Azure Blob-Speicher
Microsoft Data Lake Storage Gen2
Microsoft Azure General Purpose v2
- Siehe auch:
Syntax¶
Kopieren aus einem Stagingbereich
COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
FROM @[<namespace>.]<stage_name>[/<path>/]
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ DETAILED_OUTPUT = { TRUE | FALSE } ]
Kopieren aus einer Abfrage
COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
[ DETAILED_OUTPUT = { TRUE | FALSE } ]
Erforderliche Parameter¶
INTO @[namespace.]stage_name[/path/]
Gibt den Zielspeicherort für die kopierten Dateien an.
namespace
ist die Datenbank und/oder das Schema, in dem sich der interne oder externe Stagingbereich befindet, in Form vondatabase_name.schema_name
oderschema_name
. Der Namespace ist optional, wenn in der Benutzersitzung aktuell eine Datenbank und ein Schema verwendet werden. Andernfalls ist er erforderlich.path
ist ein optionaler, zwischen Groß- und Kleinschreibung unterscheidender Pfad im Cloudspeicherort, der einen Satz von Dateien angibt, die vom Quell-Stagingbereich oder einem bestimmten Speicherort in den Ziel-Stagingbereich kopiert werden sollen. Ihr Cloudspeicherdienst bezeichnet den Pfad möglicherweise als Präfix oder Ordner.
Bemerkung
Wenn ein Ziel- oder Quellpfadname Sonderzeichen oder Leerzeichen enthält, müssen Sie den
INTO ...
-Wert in einfache Anführungszeichen einschließen.Die Werte für
INTO ...
müssen Literalkonstanten sein. Die Werte können keine SQL-Variablen sein.
Einen Stagingbereich als Quelle verwenden¶
FROM @[namespace.]stage_name[/path/]
Gibt den Quellspeicherort an, an dem die zu kopierenden Dateien bereitgestellt werden. Die Werte, die
FROM ...
zur Verfügung gestellt werden, folgen den gleichen Spezifikationen und Einschränkungen wie die Werte vonINTO...
.
Eine Abfrage als Quelle verwenden¶
FROM (SELECT existing_url [ , new_filename ] FROM ... )
Gibt den/die Quellort(e) und optional den/die relativen Ausgabeort(e) der Kopien an. Jede von der Abfrage SELECT zurückgegebene Zeile stellt eine zu kopierende Datei dar.
existing_url
kann eine eingeschränkte URL, ein Stagingbereichname oder eine Stagingbereich-URL sein.new_filename
ist ein relativer Pfad vom Ausgabe-Stagingbereich zuINTO
. Die resultierende Datei wird dann kopiert nach:@[<namespace>.]<stage_name>[/<path>]<new_filename>
Wenn die Spalte
new_filename
nicht angegeben wird, wird der relative Pfad vonexisting_url
verwendet.
Optionale Parameter¶
FILES = ( 'file_name' [ , 'file_name' ... ] )
Gibt eine Liste von einem oder mehreren durch Komma getrennten Dateinamen an, die kopiert werden sollen. Die Dateien müssen bereits an dem von Ihnen im Befehl angegebenen Quellspeicherort bereitgestellt sein. Snowflake überspringt alle angegebenen Dateien, die nicht gefunden werden können.
Sie können maximal 1.000 Dateinamen angeben.
Diese Option wird beim Kopieren von Dateien aus der Abfrage nicht unterstützt. Verwenden Sie stattdessen die Abfrage, um die Liste der Dateinamen bereitzustellen.
Bemerkung
Um den Dateipfad für externe Stagingbereiche festzulegen, stellt Snowflake jedem Dateinamen in der Liste die URL der Stagingbereichsdefinition voran.
Snowflake fügt jedoch kein Trennzeichen zwischen dem Pfad und dem Dateinamen ein. Sie müssen explizit ein Trennzeichen (
/
) entweder am Ende der URL in der Stagingbereichsdefinition oder am Anfang jedes Dateinamens in derFILES
-Liste angeben.PATTERN = 'regex_pattern'
Gibt ein Muster für einen regulären Ausdruck zum Filtern der Liste der zu kopierenden Dateien an. Bei diesem Befehl wird der reguläre Ausdruck auf den gesamten Speicherort in der
FROM
-Klausel angewendet.Diese Option wird beim Kopieren von Dateien aus der Abfrage nicht unterstützt. Verwenden Sie stattdessen die Abfrage, um das Muster zu erkennen.
Tipp
Um die beste Leistung zu erzielen, sollten Sie Muster vermeiden, die auf eine große Anzahl von Dateien filtern.
DETAILED_OUTPUT = { TRUE | FALSE }
Gibt an, ob die Befehlsausgabe die Ergebnisse der Kopieroperation zusammenfassen oder jede kopierte Datei auflisten soll.
- Werte:
Wenn
TRUE
, enthält die Ausgabe eine Zeile für jede Datei, die an den Zielspeicherort kopiert wurde. Eine einzelne Spalte namensfile
enthält den Zielpfad (falls zutreffend) und den Dateinamen jeder kopierten Datei.Wenn
FALSE
, ist die Ausgabe eine einzelne Zeile mit der Anzahl der kopierten Dateien.
- Standard:
TRUE
Anforderungen an die Zugriffssteuerung¶
Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben (in Abhängigkeit vom Quell- und Zielspeicherort):
Berechtigung |
Objekt |
Anmerkungen |
---|---|---|
USAGE |
Externer Stagingbereich |
Erforderlich bei einem externen Quell- oder Ziel-Stagingbereich. |
READ |
Interner benannter Stagingbereich |
Erforderlich bei einem internen Quell-Stagingbereich. |
WRITE |
Interner benannter Stagingbereich |
Erforderlich bei einem interne Ziel-Stagingbereich. |
USAGE-Berechtigung für die übergeordnete Datenbank und das Schema ist erforderlich, um Operationen an einem beliebigen Objekt in einem Schema durchzuführen.
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¶
Dieser Befehl unterstützt die folgenden Aktionen nicht:
Kopieren von Dateien in oder aus Tabellen-Stagingbereichen.
Wenn Sie einen Stagingbereich als Quelle verwenden, kopieren Sie Dateien in den oder aus dem Benutzer-Stagingbereich.
Sie können nicht auf Daten in archivierten Cloudspeicherklassen zugreifen, die erst wiederhergestellt werden müssen, bevor sie abgerufen werden können. Zu diesen Archivspeicherklassen zählen Amazon S3 Glacier Flexible Retrieval, Glacier Deep Archive und Microsoft Azure Archive Storage.
Kopieren von Dateien, die größer als 5 GB sind.
Hinweise zur Ausführung dieses Befehls:
COPY FILES-Anweisungen überschreiben alle vorhandenen Dateien mit übereinstimmenden Namen am Zielspeicherort. Der Befehl entfernt nicht alle vorhandenen Dateien, die nicht mit den Namen der kopierten Dateien übereinstimmen.
Wenn eine Dateikopieroperation fehlschlägt, führt Snowflake keine automatische Bereinigung durch.
Kopieren von Dateien aus Google Cloud Storage: Eine COPY FILES-Anweisung kann fehlschlagen, wenn die Objektliste eines externen Stagingbereichs einen oder mehrere Verzeichnis-Blobs enthält. Ein Verzeichnis-Blob ist ein Pfad, der mit einem Schrägstrich (
/
) endet. In der folgenden Beispielausgabe fürLIST @<stage>
istmy_gcs_stage/load/
ein Verzeichnis-Blob.+---------------------------------------+------+----------------------------------+-------------------------------+ | name | size | md5 | last_modified | |---------------------------------------+------+----------------------------------+-------------------------------| | my_gcs_stage/load/ | 12 | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Aug 2022 16:57:43 GMT | | my_gcs_stage/load/data_0_0_0.csv.gz | 147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Aug 2022 18:13:07 GMT | +---------------------------------------+------+----------------------------------+-------------------------------+
Google erstellt Verzeichnis-Blobs, wenn Sie die Google Cloud-Konsole verwenden, um ein Verzeichnis zu erstellen.
Um dieses Problem zu vermeiden und anzugeben, welche Dateien kopiert werden sollen, verwenden Sie die Option
PATTERN
(für Kopie aus dem Stagingbereich) oderFROM
(für Kopie aus der Abfrage).Ein Beispiel dazu finden Sie unter Kopieren von Dateien mithilfe der Mustererkennung.
Für den Befehl COPY FILES fallen Datentransfer- und Computekosten an.
Datentransfer: Cloudanbieter berechnen möglicherweise Gebühren für Daten, die aus dem eigenen Netzwerk heraus übertragen werden. Um diese Kosten wieder hereinzuholen, erhebt Snowflake eine Byte-abhängige Gebühr, wenn Sie Daten aus einem internen Snowflake-Stagingbereich in den externen Stagingbereich einer anderen Region oder eines anderen Cloudanbieters kopieren. Snowflake erhebt keine Gebühren für Dateneingang (z. B. beim Kopieren von Dateien aus einem externen in einen internen Stagingbereich).
Weitere Informationen zur Abrechnung von Datenübertragungen finden Sie unter Erläuterungen zu Datentransferkosten.
Compute: COPY FILES ist ein serverloses Feature, das kein virtuelles Warehouse benötigt. In dem Einzelposten für den COPY FILES-Befehl in Ihrer Snowflake-Rechnung sind die Gebühren für Clouddienste nicht enthalten.
Weitere Informationen zur Abrechnung von Computeressourcen finden Sie unter Erläuterungen zu den Computekosten.
Bemerkung
Für einige Snowflake-Features, wie z. B. Native Apps und Arbeitsblätter, fallen COPY FILES-Gebühren an. Infolgedessen werden COPY FILES-Gebühren angezeigt, auch wenn Sie den Befehl COPY FILES nicht ausgeführt haben. Weitere Informationen zu diesen Gebühren erhalten Sie vom Snowflake-Support.
Snowflake erfasst keinen Kopierverlauf für diesen Befehl.
Beispiele¶
Dateien kopieren¶
Kopieren aller Dateien aus einem vorhandenen Quell-Stagingbereich (src_stage
) in einen vorhandenen Ziel-Stagingbereich (trg_stage
):
COPY FILES
INTO @trg_stage
FROM @src_stage;
Bemerkung
Um Dateien von oder zu einem externen Stagingbereich mit einem geschützten Speicherort zu kopieren, stellen Sie sicher, dass die Definition des Stagingbereichs Anmeldeinformationen für den Zugriff auf den Cloudspeicherort enthält.
Geben Sie die Namen der Dateien an, die aus einem vorhandenen Quell-Stagingbereich (src_stage
) in einen vorhandenen Ziel-Stagingbereich (trg_stage
) kopiert werden sollen:
COPY FILES
INTO @trg_stage
FROM @src_stage
FILES = ('file1.csv', 'file2.csv');
Kopieren von Dateien von einem bestimmten Pfad in einem bestehenden Stagingbereich (src_stage/src_path/
) zu einem bestimmten Pfad in einem bestehenden Ziel-Stagingbereich (trg_stage/trg_path/
):
COPY FILES
INTO @trg_stage/trg_path/
FROM @src_stage/src_path/;
Kopieren von Dateien mithilfe der Mustererkennung¶
Verwenden Sie die Mustererkennung, um nur komprimierte CSV-Dateien aus einem beliebigen Pfad eines vorhandenen Quell-Stagingbereich s(src_stage
) in einen vorhandenen Ziel-Stagingbereich (trg_stage
) zu laden:
COPY FILES
INTO @trg_stage
FROM @src_stage
PATTERN='.*/.*/.*[.]csv[.]gz';
Die Komponente .*
steht für null oder mehr Vorkommen eines beliebigen Zeichens. Die eckigen Klammern schließen das Punktzeichen (.
) vor einer Dateierweiterung ein.
Kopieren Sie nur unkomprimierte CSV-Dateien, deren Namen die Zeichenfolge sales
enthalten:
COPY FILES
INTO @trg_stage
FROM @src_stage
PATTERN='.*sales.*[.]csv';
Kopieren von Dateien, die durch Abfrage definiert sind¶
Kopieren einer einzelnen Datei¶
Der Dateiname bleibt derselbe wie im Quell-Stagingbereich.
COPY FILES
INTO @trg_stage
FROM (SELECT '@src_stage/file.txt');
Kopieren einer einzelnen Datei in eine beliebige Datei¶
COPY FILES
INTO @trg_stage
FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');
Kopieren von Dateien aus einer Tabelle¶
Generische Abfragen werden unterstützt, um eine allgemeine Verarbeitung zu ermöglichen.
-- Create a table with URLs
CREATE TABLE urls(src_file STRING, trg_file STRING);
INSERT INTO urls VALUES ('@src_stage/file.txt', 'new_filename.txt');
-- Insert additional URLs here
COPY FILES
INTO @trg_stage
FROM (SELECT src_file, trg_file FROM urls);
Kopieren von nur einigen Dateien¶
COPY FILES
INTO @trg_stage
FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');
Kopieren von Dateien aus einem Verzeichnis¶
COPY FILES
INTO @trg_stage
FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');