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:

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

  • Amazon S3-kompatibler Speicher

Siehe auch:

Externe Stagingbereiche, Interne Stagingbereiche

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 } ]
Copy

Kopieren aus einer Abfrage

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]
Copy

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.

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 von INTO....

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 zu INTO. 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 von existing_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 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):

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ü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.

  • 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;
Copy

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

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/;
Copy

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';
Copy

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';
Copy

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

Kopieren einer einzelnen Datei in eine beliebige Datei

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

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

Kopieren von nur einigen Dateien

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

Kopieren von Dateien aus einem Verzeichnis

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