COPY FILES

Dateien von einem Quellspeicherort in einen Stagingbereich kopieren. Sie können entweder einen Stagingbereich oder eine Abfrage als Quelle für die zu kopierenden Dateien verwenden.

  • Verwenden Sie einen Stagingbereich als Quelle, um Dateien von einem Stagingbereich in einen anderen zu kopieren, ohne sie umzubenennen.

  • Verwenden Sie eine Abfrage als Quelle für die folgenden Aufgaben:

Sie können von und zu bestehenden benannte Stagingbereiche kopieren, 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

Snowflake-Git-Repository-Klon

Interner benannter Stagingbereich

Snowflake-Git-Repository-Klon

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, Snowflake Git-Repository-Klon

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 Quellspeicherort und optional den relativen Speicherort für die kopierten Dateien an. Jede Zeile, die die SELECT-Abfrage zurückgibt, steht für eine zu kopierende Datei.

  • existing_url ist eine Bereichs-URL, Stagingbereichsname oder Stagingbereich-URL.

  • new_filename ist ein optionaler relativer Pfad von dem Ausgabe-Stagingbereich, der für die angegeben wurde INTO -Klausel

Snowflake kopiert die Datei an den folgenden Speicherort:

@[<namespace>.]<stage_name>[/<path>]<new_filename>

Wenn Sie keinen Wert für new_filename angeben, verwendet Snowflake den relativen Pfad der existing_url.

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 mit einer Abfrage

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 und Umbenennen einer einzelnen Datei

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

Kopieren aller Dateien aus einer Tabelle

Um mehrere Dateien mit einer Abfrage zu kopieren, können Sie eine generische Abfrage verwenden.

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

Dieses Beispiel verwendet einen Filter, um Dateien zu kopieren, die einem Muster entsprechen.

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

Kopieren von Dateien aus einer Verzeichnistabelle

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