Kategorien:

DML-Befehle – Laden von Daten

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.

  • Die folgenden Snowflake-Clients unterstützen PUT nicht:

    • Go-Snowflake-Treiber

    • .NET-Treiber

    • Node.js-Treiber

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

Wobei:

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

Erforderliche Parameter

file://Pfad_zu_Datei/Dateiname

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

  • Pfad_zu_Datei ist der Pfad des lokalen Verzeichnisses zu den hochzuladenden Dateien. Wenn sich die Dateien im Stammverzeichnis (oder Unterverzeichnis) auf dem Clientcomputer befinden:

    Linux/Mac

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

    Windows

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

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

Der URI kann in einfache Anführungszeichen eingeschlossen werden, was Sonderzeichen, einschließlich Leerzeichen, in Verzeichnis- und Dateinamen erlaubt; der Laufwerks- und Pfadtrenner ist jedoch für alle unterstützten Betriebssysteme ein Schrägstrich (/) (z. B. 'file://C:/temp/load data' für einen Pfad in Windows, der ein Verzeichnis mit dem Namen load data enthält).

internalStage

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

@[Namespace.]Name_des_internen_Stagingbereichs[/Pfad]

Dateien werden in den angegebenen benannten internen Stagingbereich hochgeladen.

@[Namespace.]%Tabellenname[/Pfad]

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

@~[/Pfad]

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.

  • Pfad 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.

Die Zeichenfolge kann in einfache Anführungszeichen eingeschlossen werden, was Sonderzeichen, einschließlich Leerzeichen, in Speicherortnamen erlaubt (z. B. '@"my stage"' für einen Stagingbereich mit dem Namen "my stage").

Optionale Parameter

PARALLEL = Ganzzahl

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.

Wenn Sie versuchen, den PUT-Befehl für eine Datei auszuführen, dies jedoch nicht möglich ist, da bereits eine Datei mit demselben Namen im Stagingbereich vorhanden ist, können Sie folgende Aktionen ausführen:

  • Warten Sie, bis die Daten der vorhandenen Datei geladen sind, und wiederholen Sie dann PUT.

  • Benennen Sie die Datei um, die Sie mit PUT verwenden möchten.

  • Setzen Sie 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.

Die folgenden Plattformen unterstützen die OVERWRITE-Option:

  • Amazon AWS

  • Microsoft Azure

GCP, die Google-Cloudplattform, unterstützt OVERWRITE=FALSE nicht. Bei GCP lädt der PUT-Befehl die Datei immer hoch, auch wenn eine Datei mit demselben Namen vorhanden ist und OVERWRITE auf „false“ gesetzt ist.

Die folgenden Treiber und Konnektoren unterstützen die Option OVERWRITE:

  • Snowflake-ODBC-Treiber

  • Snowflake-JDBC-Treiber

  • Snowflake-Python-Konnektor

Die Option OVERWRITE wird auch in SnowSQL unterstützt.

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, um Datendateien hochzuladen, oder konsultieren Sie die Dokumentation für den jeweiligen Snowflake-Client, um die Unterstützung für diesen Befehl zu überprüfen.

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

  • Mit dem Befehl werden keine Dateien erstellt oder umbenannt. Das Präfix (falls vorhanden) in dem angegebenen internen Stagingbereich bezieht sich auf vorhandene Dateien und nicht auf neue Dateien.

  • Hochgeladene Dateien werden automatisch mit 128-Bit- oder 256-Bit-Schlüsseln verschlüsselt. Der Kontoparameter CLIENT_ENCRYPTION_KEY_SIZE gibt den zur Verschlüsselung der Dateien verwendeten Größenschlüssel an.

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

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

Tipp

Aus Sicherheitsgründen läuft der Befehl nach einer festgelegten Zeit ab. 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 10 bis 100 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;

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;

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;

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;