PUT

Lädt Datendateien aus einem lokalen Verzeichnis/Ordner eines Clientcomputers in einen der folgenden Snowflake-Stagingbereiche hoch:

  • Benannter interner Stagingbereich.

  • Interner Stagingbereich für eine angegebene Tabelle.

  • Interner Stagingbereich für den aktuellen Benutzer.

Nachdem die Dateien in den Stagingbereich geladen wurden, können die Daten in den Dateien mit dem Befehl COPY INTO <Tabelle> in eine Tabelle geladen werden.

Bemerkung

  • PUT unterstützt nicht das Hochladen von Dateien in externe Stagingbereiche. Verwenden Sie die vom Clouddienst bereitgestellten Dienstprogramme, um Dateien in externe Stagingbereiche hochzuladen.

  • Der ODBC-Treiber unterstützt PUT mit Snowflake-Konten, die auf den folgenden Plattformen gehostet werden:

    • Amazon Web Services (mit ODBC-Treiberversion 2.17.5 und höher).

    • Google Cloud Platform (mit ODBC-Treiberversion 2.21.5 und höher).

    • Microsoft Azure (mit ODBC-Treiberversion 2.20.2 und höher).

Siehe auch:

GET, LIST, REMOVE

Syntax

PUT file://<path_to_file>/<filename> internalStage
    [ PARALLEL = <integer> ]
    [ AUTO_COMPRESS = TRUE | FALSE ]
    [ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
    [ OVERWRITE = TRUE | FALSE ]
Copy

Wobei:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
Copy

Erforderliche Parameter

file://path_to_file/filename

Gibt die URI für die Datendatei(en) auf dem Clientcomputer an. Dabei gilt Folgendes:

  • path_to_file ist der lokale Verzeichnispfad zu den hochzuladenden Dateien.

  • filename ist der Name der hochzuladenden Datei(en). Platzhalterzeichen (*, ?) werden unterstützt, um das Hochladen mehrerer Dateien in ein Verzeichnis zu ermöglichen.

Die URI-Formatierung ist je nach Client-Betriebssystem unterschiedlich:

Linux/macOS

Sie müssen den ersten Schrägstrich in den Pfad einbeziehen (z. B. file:///tmp/load).

Wenn der Verzeichnispfad und/oder der Dateiname Sonderzeichen enthält, muss die gesamte Datei-URI in einfache Anführungszeichen gesetzt werden.

Windows

Sie müssen das Laufwerk und den Backslash in den Pfad einbeziehen (z. B. file://C:\temp\load).

Wenn der Verzeichnispfad und/oder der Dateiname Sonderzeichen enthält, muss die gesamte Datei-URI in einfache Anführungszeichen gesetzt werden. Beachten Sie, dass das Trennzeichen ein Schrägstrich (/) ist, der in URIs eingeschlossen ist (z. B. 'file://C:/temp/load data' für einen Pfad in Windows, der ein Verzeichnis namens load data enthält).

internalStage

Gibt den Ort in Snowflake an, an den die Dateien hochgeladen werden sollen:

@[namespace.]int_stage_name[/path]

Dateien werden in den angegebenen benannten internen Stagingbereich hochgeladen.

@[namespace.]%table_name[/path]

Dateien werden für die angegebene Tabelle in den Stagingbereich hochgeladen.

@~[/path]

Dateien werden für den aktuellen Benutzer in den Stagingbereich hochgeladen.

Wobei:

  • namespace ist die Datenbank und/oder das Schema, in dem sich der benannte interne Stagingbereich oder die Tabelle befindet. Die Angabe ist optional, wenn in der Sitzung aktuell eine Datenbank und ein Schema verwendet werden, andernfalls ist die Angabe obligatorisch.

  • path ist ein optionaler Pfad mit Unterscheidung von Groß-/Kleinschreibung für Dateien am Cloudspeicherort (d. h. Dateien haben Namen, die mit einer gemeinsamen Zeichenfolge beginnen), wodurch der Zugriff auf bestimmte Dateien eingegrenzt wird. Pfade werden von den verschiedenen Cloudspeicherdiensten alternativ als Präfixe oder Ordner bezeichnet.

Bemerkung

Wenn der Stagingbereichsname oder -pfad Leerzeichen oder Sonderzeichen enthält, muss er in einfache Anführungszeichen eingeschlossen werden (z. B. '@"my stage"' für einen Stagingbereich mit dem Namen "my stage").

Optionale Parameter

PARALLEL = integer

Gibt die Anzahl der Threads an, die zum Hochladen von Dateien verwendet werden sollen. Beim Hochladen werden die Batches der Datendateien nach Größe getrennt:

  • Kleine Dateien (<64 MB komprimiert oder unkomprimiert) werden parallel als einzelne Dateien bereitgestellt.

  • Größere Dateien werden automatisch in Blöcke aufgeteilt, gleichzeitig bereitgestellt und im Ziel-Stagingbereich wieder zusammengefügt. Ein einzelner Thread kann mehrere Blöcke hochladen.

Wenn Sie die Anzahl der Threads erhöhen, kann die Leistung beim Hochladen großer Dateien verbessert werden.

Unterstützte Werte: Jeder ganzzahlige Wert von 1 (keine Parallelität) bis 99 (99 Threads zum Hochladen von Dateien verwenden).

Standard: 4

Bemerkung

Für ältere Versionen von Snowflake-Treibern gilt ein Limit von 16 MB (anstelle von 64 MB). Dazu zählen:

  • JDBC-Treiberversionen vor 3.12.1

  • ODBC-Treiberversionen vor 2.20.5

  • Python-Konnektorversionen vor 2.2.0

AUTO_COMPRESS = TRUE | FALSE

Gibt an, ob Snowflake während des Uploads Dateien mit gzip komprimiert:

  • TRUE: Dateien werden komprimiert (wenn sie nicht bereits komprimiert sind).

  • FALSE: Dateien werden nicht komprimiert (d. h. die Dateien werden so wie sie sind hochgeladen).

Diese Option unterstützt keine anderen Komprimierungstypen. Wenn Sie einen anderen Komprimierungstyp verwenden möchten, komprimieren Sie die Datei separat, bevor Sie den Befehl PUT ausführen. Identifizieren Sie dann den Komprimierungstyp mit der Option SOURCE_COMPRESSION.

Stellen Sie sicher, dass in Ihrem lokalen Ordner ausreichend Speicherplatz für Snowflake vorhanden ist, um die Datendateien vor dem Staging zu komprimieren. Stellen Sie bei Bedarf die Umgebungsvariable TEMP, TMPDIR oder TMP in Ihrem Betriebssystem so ein, dass sie auf einen lokalen Ordner verweist, der zusätzlichen freien Speicherplatz enthält.

Standard: TRUE

SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

Gibt die Komprimierungsmethode für bereits komprimierte Dateien an, die im Stagingbereich bereitgestellt werden:

Unterstützte Werte

Anmerkungen

AUTO_DETECT

Der Komprimierungsalgorithmus wird automatisch erkannt, mit Ausnahme von Brotli-komprimierten Dateien, die derzeit nicht automatisch erkannt werden können. Wenn Sie Brotli-komprimierte Dateien laden, verwenden Sie explizit BROTLI anstelle von AUTO_DETECT.

GZIP

BZ2

BROTLI

Muss beim Laden von Brotli-komprimierten Dateien verwendet werden.

ZSTD

Zstandard v0.8 (und höher) wird unterstützt.

DEFLATE

Deflate-komprimierte Dateien (mit zlib-Header, RFC1950).

RAW_DEFLATE

Raw Deflate-komprimierte Dateien (ohne Header, RFC1951).

NONE

Zu ladende Datendateien wurden nicht komprimiert.

Standard: AUTO_DETECT

Bemerkung

Snowflake verwendet diese Option, um zu ermitteln, wie die Datendateien komprimiert wurden, sodass sie dekomprimiert und die Daten zum Laden extrahiert werden können. Diese Option wird nicht verwendet, um die Dateien zu komprimieren.

Das Hochladen von Dateien, die mit anderen Dienstprogrammen (z. B. LZIP, LZMA, LZOP und XZ) komprimiert wurden, wird derzeit nicht unterstützt.

OVERWRITE = TRUE | FALSE

Gibt an, ob Snowflake beim Hochladen eine vorhandene Datei mit demselben Namen überschreibt:

  • TRUE: Eine vorhandene Datei mit demselben Namen wird überschrieben.

  • FALSE: Eine vorhandene Datei mit demselben Namen wird nicht überschrieben.

    Beachten Sie, dass eine LIST-Operation im Stagingbereich im Hintergrund ausgeführt wird, was die Leistung der PUT-Operation beeinträchtigen kann.

    Wenn der Versuch, PUT auf einer Datei auszuführen, fehlschlägt, weil eine Datei mit demselben Namen im Ziel-Stagingbereich vorhanden ist, stehen die folgenden Optionen zur Verfügung:

    • Laden Sie die Daten aus der vorhandenen Datei in eine oder mehrere Tabellen, und entfernen Sie die Datei aus dem Stagingbereich. Führen Sie den PUT-Befehl erneut auf einer Datei aus, die neue oder aktualisierte Daten enthält, um sie in den Stagingbereich hochzuladen.

    • Benennen Sie die lokale Datei um, und führen Sie dann die PUT-Operation erneut aus.

    • Verwenden Sie die PUT-Anweisung mit OVERWRITE = TRUE. Tun Sie dies nur, wenn es tatsächlich sicher ist, eine Datei mit Daten zu überschreiben, die möglicherweise noch nicht in Snowflake geladen wurden.

Beachten Sie, dass bei Hosting Ihres Snowflake-Kontos auf Google Cloud Platform PUT-Anweisungen nicht erkannt werden, wenn der Parameter OVERWRITE auf TRUE gesetzt ist. Eine PUT-Operation überschreibt immer alle vorhandenen Dateien im Ziel-Stagingbereich mit den lokalen Dateien, die Sie hochladen.

Die folgenden Clients unterstützen die OVERWRITE-Option bei Snowflake-Konten, die auf Amazon Web Services oder Microsoft Azure gehostet werden:

  • SnowSQL

  • Snowflake-ODBC-Treiber:

  • Snowflake-JDBC-Treiber:

  • Snowflake-Konnektor für Python

Unterstützte Werte: TRUE, FALSE.

Standard: FALSE.

Nutzungshinweise

  • Der Befehl kann nicht über die Seite Worksheets Worksheet tab der Snowflake-Weboberfläche ausgeführt werden. Verwenden Sie stattdessen den SnowSQL-Client oder Treiber, um Datendateien hochzuladen, oder informieren Sie sich in der Dokumentation des jeweiligen Snowflake-Clients über die Verwendung dieses Befehls.

  • Datei-Globbing-Muster (d. h. Platzhalter) werden unterstützt.

  • Mit diesem Befehl können Dateien nicht erstellt oder umbenannt werden.

  • Alle Dateien, die in internen Stagingbereichen zum Laden/Entladen von Daten gespeichert werden, werden serverseitig automatisch mit starker AES-256-Verschlüsselung verschlüsselt. Snowflake bietet standardmäßig eine zusätzliche clientseitige Verschlüsselung mit einem 128-Bit-Schlüssel (mit der Option, einen 256-Bit-Schlüssel zu konfigurieren). Weitere Informationen dazu finden Sie unter Verschlüsselungstypen für interne Stagingbereiche.

  • Der Befehl ignoriert alle doppelten Dateien, die Sie in denselben Stagingbereich hochladen möchten. Eine doppelte Datei ist eine nicht geänderte Datei, die den gleichen Namen wie eine bereits vorhandene Stagingdatei hat.

    Um eine bereits vorhandene Stagingdatei zu überschreiben, müssen Sie die hochgeladene Datei so ändern, dass sie sich von der Stagingdatei unterscheidet. Dies führt zu einer neuen Prüfsumme für die neue bereitgestellte Stagingdatei.

Tipp

Aus Sicherheitsgründen verliert der Befehl nach einer festgelegten Zeit seine Gültigkeit. Dies kann beim Laden großer, unkomprimierter Datendateien auftreten. Wir empfehlen, große Datendateien vor dem Hochladen mit einem der unterstützten Komprimierungstypen zu komprimieren, um Timeout-Probleme zu vermeiden. Geben Sie dann den Komprimierungstyp für die Dateien mit der Option SOURCE_COMPRESSION an.

Sie können auch den Wert der Option PARALLEL erhöhen. Dies kann die Leistung beim Hochladen großer Datendateien verbessern.

Um die parallelen Operationen beim Laden von Daten in Tabellen zu nutzen (mit dem Befehl COPY INTO <Tabelle>), empfehlen wir außerdem die Verwendung von komprimierten Datendateien mit einer Größe von etwa 100 bis 250 MB. Wenn Ihre Datendateien größer sind, sollten Sie ein Drittanbietertool in Betracht ziehen, um sie in kleinere Dateien aufzuteilen, bevor Sie sie komprimieren und hochladen.

Beispiele

Laden Sie eine Datei mit dem Namen mydata.csv im Verzeichnis /tmp/data (in einer Linux- oder macOS-Umgebung) in einen internen Stagingbereich mit dem Namen my_int_stage hoch:

PUT file:///tmp/data/mydata.csv @my_int_stage;
Copy

Laden Sie eine Datei mit dem Namen orders_001.csv im Verzeichnis /tmp/data (in einer Linux- oder macOS-Umgebung) in den Stagingbereich der Tabelle orderstiny_ext hoch, wobei die automatische Datenkomprimierung deaktiviert ist:

PUT file:///tmp/data/orders_001.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
Copy

Gleiches Beispiel wie oben, jedoch mit Platzhalterzeichen im Dateinamen zum Hochladen mehrerer Dateien:

PUT file:///tmp/data/orders_*01.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;
Copy

Laden Sie eine Datei mit dem Namen mydata.csv in das Verzeichnis C:\temp\data (in einer Windows-Umgebung) im Stagingbereich des aktuellen Benutzers unter Verwendung der automatischen Datenkomprimierung hoch:

PUT file://C:\temp\data\mydata.csv @~ AUTO_COMPRESS=TRUE;
Copy

Ähnlich wie im vorherigen Beispiel, aber laden Sie die Datei aus dem Verzeichnis C:\temp\load data hoch (in einer Windows-Umgebung):

PUT 'file://C:\temp\load data\mydata.csv' @~ AUTO_COMPRESS=TRUE;
Copy