COPY FILES¶

Syntax¶

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM @[<namespace>.]<stage_name>[/<path>/]
  [ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
  [ PATTERN = '<regex_pattern>' ]
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

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 von database_name.schema_name oder schema_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.

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 der FILES-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 namens file 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):

USAGE-Berechtigung für die übergeordnete Datenbank und das Schema ist erforderlich, um Operationen an einem beliebigen Objekt in einem Schema durchzuführen. Beachten Sie, dass eine Rolle, die eine beliebige Berechtigung für ein Schema erhalten hat, es dieser Rolle erlaubt, das Schema aufzulösen. Zum Beispiel kann eine Rolle, der die CREATE-Berechtigung für ein Schema gewährt wurde, Objekte in diesem Schema erstellen, ohne auch USAGE für dieses Schema gewährt bekommen zu haben.

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ür LIST @<stage> ist my_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) oder FROM (für Kopie aus der Abfrage).

    Ein Beispiel dazu finden Sie unter Kopieren von Dateien mithilfe der Mustererkennung.

  • Snowflake verwendet beim Hochladen auf Amazon S3 und Google Cloud Storage mehrteilige Uploads. Um zu verhindern, dass sich unvollständige Uploads ansammeln, empfehlen wir Ihnen, eine Lebenszyklusregel festzulegen. Eine Anleitung dazu finden Sie in der Dokumentation Amazon S3 oder Google Cloud Storage.

• 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¶

COPY FILES
  INTO @trg_stage
  FROM @src_stage;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  FILES = ('file1.csv', 'file2.csv');

COPY FILES
  INTO @trg_stage/trg_path/
  FROM @src_stage/src_path/;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*/.*/.*[.]csv[.]gz';

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*sales.*[.]csv';

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt');

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');

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

COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');

COPY FILES
  INTO @trg_stage
  FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');