Kategorien:

DML-Befehle – Datenentladen

COPY INTO <Speicherort>

Entlädt Daten aus einer Tabelle (oder Abfrage) in eine oder mehrere Dateien an einem der folgenden Speicherorte:

  • Benannter interner Stagingbereich (oder Tabellen-/Benutzer-Stagingbereich). Die Dateien können dann mit dem Befehl GET aus dem Stagingbereich bzw. vom Speicherort heruntergeladen werden.

  • Benannter externer Stagingbereich, der auf einen externen Speicherort verweist (Amazon S3, Google Cloud Storage oder Microsoft Azure).

  • Externer Speicherort (Amazon S3, Google Cloud Storage oder Microsoft Azure).

Siehe auch:

COPY INTO <Tabelle>

Unter diesem Thema:

Syntax

COPY INTO { internalStage | externalStage | externalLocation }
     FROM { [<namespace>.]<table_name> | ( <query> ) }
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | PARQUET } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ HEADER ]

Wobei:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
externalStage ::=
  @[<namespace>.]<ext_stage_name>[/<path>]
externalLocation (for Amazon S3) ::=
  's3://<bucket>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = `<string>` AWS_SECRET_KEY = `<string>` [ AWS_TOKEN = `<string>` ] } } ) }` ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] |
                   [ TYPE = NONE ] ) ]
externalLocation (for Google Cloud Storage) ::=
  'gcs://<bucket>[/<path>]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] ) ]
externalLocation (for Microsoft Azure) ::=
  'azure://<account>.blob.core.windows.net/<container>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = <string> ] ) }` ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | NONE } ] [ MASTER_KEY = '<string>' ] ) ]
formatTypeOptions ::=
-- If FILE_FORMAT = ( TYPE = CSV ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<character>' | NONE
     FIELD_DELIMITER = '<character>' | NONE
     FILE_EXTENSION = '<string>'
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( '<string1>' [ , '<string2>' , ... ] )
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
-- If FILE_FORMAT = ( TYPE = JSON ... )
     COMPRESSION = AUTO | GZIP | BZ2 | DEFLATE | RAW_DEFLATE | NONE
     FILE_EXTENSION = '<string>'
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
copyOptions ::=
     OVERWRITE = TRUE | FALSE
     SINGLE = TRUE | FALSE
     MAX_FILE_SIZE = <num>
     INCLUDE_QUERY_ID = TRUE | FALSE
     DETAILED_OUTPUT = TRUE | FALSE

Erforderliche Parameter

INTO ...

Gibt den internen oder externen Speicherort an, an dem die Datendateien entladen werden:

@[Namespace.]Name_des_internen_Stagingbereichs[/Pfad]

Dateien werden in den angegebenen benannten internen Stagingbereich entladen.

@[Namespace.]Name_des_externen_Stagingbereichs[/Pfad]

Die Dateien werden in den angegebenen benannten externen Stagingbereich entladen.

@[Namespace.]%Tabellenname[/Pfad]

Die Dateien werden in den Stagingbereich der angegebenen Tabelle entladen.

@~[/Pfad]

Die Dateien werden in den Stagingbereich des aktuellen Benutzers entladen.

's3://Bucket[/Pfad]'

Dateien werden an den angegebenen externen Speicherort (S3-Bucket) entladen. Es können zusätzliche Parameter erforderlich sein. Weitere Informationen dazu finden Sie unter Zusätzliche Cloudanbieterparameter (unter diesem Thema).

'azure://Konto.blob.core.windows.net/Container[/Pfad]'

Dateien werden an den angegebenen externen Speicherort (Azure-Container) entladen. Es können zusätzliche Parameter erforderlich sein. Weitere Informationen dazu finden Sie unter Zusätzliche Cloudanbieterparameter (unter diesem Thema).

Wobei:

  • Namespace ist die Datenbank und/oder das Schema, in dem sich der interne oder externe Stagingbereich befindet, in Form von Datenbankname.Schemaname oder Schemaname. Es ist optional, wenn in der Benutzersitzung aktuell eine Datenbank und ein Schema verwendet werden, andernfalls ist es erforderlich.

  • Der optionale Parameter Pfad gibt ein Ordner- und Dateinamenpräfix für die Datei(en) an, die entladene Daten enthalten. Wenn ein Dateinamenpräfix nicht in Pfad enthalten ist, werden die Dateinamen für die generierten Datendateien mit dem Präfix data_ generiert.

    Relative Pfadmodifikatoren wie /./ und /../ werden literal interpretiert, da „Pfade“ literale Präfixe für einen Namen sind. Beispiel:

    -- S3 bucket
    COPY INTO 's3://mybucket/./../a.csv' FROM mytable;
    
    -- Azure container
    COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv' FROM mytable;
    

    In diesen COPY-Anweisungen erstellt Snowflake eine Datei, die am Speicherort literal ./../a.csv benannt ist.

Bemerkung

Die URI-Zeichenfolge für einen externen Speicherort (Amazon S3, Google Cloud Storage oder Microsoft Azure) muss in einfache Anführungszeichen eingeschlossen werden. Sie können jedoch jede Zeichenfolge in einfache Anführungszeichen setzen, wodurch Sonderzeichen, einschließlich Leerzeichen, in Speicherort- und Dateinamen verwendet werden können. Beispiel:

-- Stages
COPY INTO '@mystage/path 1/file 1.csv' FROM mytable;
COPY INTO '@%mytable/path 1/file 1.csv' FROM mytable;
COPY INTO '@~/path 1/file 1.csv' FROM mytable;

-- S3 bucket
COPY INTO 's3://mybucket 1/prefix 1/file 1.csv' FROM mytable;

-- Azure container
COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/encrypted_files/file 1.csv' FROM mytable;
FROM ...

Gibt die Quelle der zu entladenden Daten an, die entweder eine Tabelle oder eine Abfrage sein kann:

[Namespace.]Tabellenname

Gibt den Namen der Tabelle an, aus der die Daten entladen werden.

Der Namespace gibt optional die Datenbank und/oder das Schema, in dem sich die Tabelle befindet, in Form von Datenbankname.Schemaname oder Schemaname an. Es ist optional, wenn in der Benutzersitzung aktuell eine Datenbank und ein Schema verwendet werden, andernfalls ist es erforderlich.

( Abfrage )

SELECT-Anweisung, die Daten zurückgibt, die in Dateien entladen werden sollen. Sie können die Anzahl der zurückgegebenen Zeilen begrenzen, indem Sie eine LIMIT / FETCH-Klausel in der Abfrage angeben.

Bemerkung

Stellen Sie beim Umwandeln von Spaltenwerten in einen Datentyp mithilfe der Funktion CAST , :: sicher, dass der Datentyp alle Spaltenwerte unterstützt. Wenn Werte für den angegebenen Datentyp zu lang sind, könnten sie abgeschnitten werden.

Zusätzliche Cloudanbieterparameter

STORAGE_INTEGRATION = Integrationsname oder . CREDENTIALS = ( cloudspezifische_Anmeldeinformationen )

Für die Verwendung in Ad-hoc-COPY-Anweisungen (Anweisungen, die nicht auf einen externen Stagingbereich verweisen.) Gibt die Sicherheitsanmeldeinformationen für die Verbindung zum Cloudanbieter und für den Zugriff auf den privaten Speichercontainer an, in dem die entladenen Dateien bereitgestellt werden.

Nur zum Entladen in einen externen privaten Cloudspeicherort erforderlich; nicht erforderlich für öffentliche Buckets/Container

Amazon S3

STORAGE_INTEGRATION = Integrationsname

Gibt den Namen der Speicherintegration an, mit der die Authentifizierungsverantwortung für den externen Cloudspeicher an eine Snowflake-Entität für Identitäts- und Zugriffsverwaltung (IAM) delegiert wird. Weitere Details dazu finden Sie unter CREATE STORAGE INTEGRATION.

Bemerkung

Wir empfehlen dringend die Verwendung von Speicherintegrationen. Mit dieser Option wird vermieden, dass beim Erstellen von Stagingbereichen oder Laden von Daten mithilfe des Parameters CREDENTIALS Cloudspeicher-Anmeldeinformationen angegeben werden müssen.

CREDENTIALS = ( AWS_KEY_ID = 'Zeichenfolge' AWS_SECRET_KEY = 'Zeichenfolge' [ AWS_TOKEN = 'Zeichenfolge' ] ) oder . CREDENTIALS = ( AWS_ROLE = 'Zeichenfolge' )

Gibt die Sicherheits-Anmeldeinformationen für die Verbindung mit AWS und den Zugriff auf den privaten S3-Bucket an, in dem die entladenen Dateien bereitgestellt werden. Weitere Informationen dazu finden Sie unter Konfigurieren des sicheren Zugriffs auf Amazon S3.

Die von Ihnen angegebenen Anmeldeinformationen hängen davon ab, ob Sie die Zugriffsberechtigungen von Snowflake für den Bucket einem/einer AWS IAM (Identity & Access Management)-Benutzer oder -Rolle zugeordnet haben:

  • IAM-Benutzer: Temporäre IAM-Zugangsdaten sind erforderlich. Temporäre (auch bekannt als „Scoped“) Anmeldeinformationen werden vom AWS Security Token Service (STS) generiert und bestehen aus drei Komponenten:

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    Alle drei sind erforderlich, um auf einen privaten Bucket zuzugreifen. Nach einem angegebenen Zeitraum verfallen die temporären Anmeldeinformationen und können nicht mehr verwendet werden. Sie müssen dann einen neuen Satz gültiger temporärer Anmeldeinformationen generieren.

    Wichtig

    COPY-Befehle enthalten komplexe Syntax und sensible Informationen, wie z. B. Anmeldeinformationen. Darüber hinaus werden sie häufig ausgeführt und oft in Skripten oder Arbeitsblättern gespeichert, was dazu führen kann, dass sensible Informationen versehentlich freigelegt werden. Mit dem Befehl COPY können permanente (auch bekannt als „langfristige“) Anmeldeinformationen verwendet werden; aus Sicherheitsgründen sollten Sie jedoch permanente Anmeldeinformationen in COPY-Befehlen nicht verwenden. Verwenden Sie stattdessen temporäre Anmeldeinformationen.

    Wenn Sie permanente Anmeldeinformationen verwenden müssen, verwenden Sie externe Stagingbereiche, für die die Anmeldeinformationen einmal eingegeben und sicher gespeichert werden, wodurch das Risiko einer Gefährdung minimiert wird.

  • IAM-Rolle: Lassen Sie die Sicherheitsanmeldeinformationen und Zugriffsschlüssel weg. Identifizieren Sie stattdessen die Rolle mit AWS_ROLE, und geben Sie den AWS-Rollen-ARN (Amazon Resource Name) an.

    Wichtig

    Die Möglichkeit, eine AWS IAM-Rolle für den Zugriff auf einen privaten S3-Bucket zum Laden oder Entladen von Daten zu verwenden, ist jetzt veraltet (d. h. die Unterstützung wird in einem zukünftigen Release entfernt, TBD). Es wird dringend empfohlen, alle vorhandenen S3-Stagingbereiche zu ändern, die diese Funktion verwenden, um stattdessen auf Speicherintegrationsobjekte zu verweisen. Eine Anleitung dazu finden Sie unter Option 1: Konfigurieren einer Snowflake-Speicherintegration.

Google Cloud Storage

STORAGE_INTEGRATION = Integrationsname

Gibt den Namen der Speicherintegration an, mit der die Authentifizierungsverantwortung für den externen Cloudspeicher an eine Snowflake-Entität für Identitäts- und Zugriffsverwaltung (IAM) delegiert wird. Weitere Details dazu finden Sie unter CREATE STORAGE INTEGRATION.

Microsoft Azure

STORAGE_INTEGRATION = Integrationsname

Gibt den Namen der Speicherintegration an, mit der die Authentifizierungsverantwortung für den externen Cloudspeicher an eine Snowflake-Entität für Identitäts- und Zugriffsverwaltung (IAM) delegiert wird. Weitere Details dazu finden Sie unter CREATE STORAGE INTEGRATION.

Bemerkung

Wir empfehlen dringend die Verwendung von Speicherintegrationen. Mit dieser Option wird vermieden, dass beim Erstellen von Stagingbereichen oder Laden von Daten mithilfe des Parameters CREDENTIALS Cloudspeicher-Anmeldeinformationen angegeben werden müssen.

CREDENTIALS = ( AZURE_SAS_TOKEN = 'Zeichenfolge' )

Gibt das SAS-Token (Shared Access Signature-Token) für die Verbindung mit Azure und den Zugriff auf den privaten Bucket an, in dem die Dateien mit Daten bereitgestellt werden. Die Anmeldeinformationen werden von Azure generiert.

ENCRYPTION = ( cloudspezifische_Verschlüsselung )

Zur Verwendung in Ad-hoc-COPY-Anweisungen (Anweisungen, die nicht auf einen benannten externen Stagingbereich verweisen). Nur zum Entladen von Daten in Dateien an verschlüsselten Speicherorten erforderlich

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] )

TYPE = ...

Gibt den verwendeten Verschlüsselungstyp an. Mögliche Werte sind:

  • AWS_CSE: Clientseitige Verschlüsselung (erfordert einen MASTER_KEY-Wert). Derzeit kann der von Ihnen bereitgestellte clientseitige Hauptschlüssel nur ein symmetrischer Schlüssel sein. Beachten Sie, dass Snowflake bei Angabe eines MASTER_KEY-Werts davon ausgeht, dass TYPE = AWS_CSE (d. h. wenn ein MASTER_KEY-Wert angegeben wird, ist TYPE nicht erforderlich).

  • AWS_SSE_S3: Serverseitige Verschlüsselung, die keine zusätzlichen Verschlüsselungseinstellungen erfordert.

  • AWS_SSE_KMS: Serverseitige Verschlüsselung, die einen optionalen KMS_KEY_ID-Wert akzeptiert.

Weitere Informationen zu den Verschlüsselungsarten finden Sie in der AWS-Dokumentation für clientseitige Verschlüsselung oder serverseitige Verschlüsselung.

MASTER_KEY = 'Zeichenfolge' (gilt nur für AWS_CSE-Verschlüsselung)

Gibt den clientseitigen Hauptschlüssel an, mit dem die Dateien im Bucket verschlüsselt wurden. Der Hauptschlüssel muss ein 128-Bit- oder 256-Bit-Schlüssel in Base64-codierter Form sein.

KMS_KEY_ID = 'Zeichenfolge' (gilt nur für AWS_SSE_KMS-Verschlüsselung)

Gibt optional die ID für den AWS KMS-verwalteten Schlüssel an, der zum Verschlüsseln von Dateien verwendet wird, die in den Bucket entladen wurden. Wenn kein Wert angegeben wird, werden Dateien beim Entladen mit Ihrer standardmäßigen KMS-Schlüssel-ID verschlüsselt.

Beachten Sie, dass dieser Wert beim Laden von Daten ignoriert wird.

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] )

TYPE = ...

Gibt den verwendeten Verschlüsselungstyp an. Mögliche Werte sind:

  • GCS_SSE_KMS: Serverseitige Verschlüsselung, die einen optionalen KMS_KEY_ID-Wert akzeptiert.

Weitere Informationen dazu finden Sie in der Dokumentation zu Google Cloud Platform:

KMS_KEY_ID = 'Zeichenfolge' (gilt nur für GCS_SSE_KMS-Verschlüsselung)

Gibt optional die ID für den Cloud-KMS-verwalteten Schlüssel an, der zum Verschlüsseln von Dateien verwendet wird, die in den Bucket entladen wurden. Wenn kein Wert angegeben ist, werden Dateien beim Entladen in den Bucket mit Ihrer standardmäßigen KMS-Schlüssel-ID verschlüsselt.

Beachten Sie, dass dieser Wert beim Laden von Daten ignoriert wird. Die Ladeoperation sollte erfolgreich sein, wenn das Dienstkonto über ausreichende Berechtigungen zum Entschlüsseln von Daten im Bucket verfügt.

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | NONE ] [ MASTER_KEY = 'Zeichenfolge' ] )

TYPE = ...

Gibt den verwendeten Verschlüsselungstyp an. Mögliche Werte sind:

MASTER_KEY = 'Zeichenfolge' (gilt nur für AZURE_CSE-Verschlüsselung)

Gibt den clientseitigen Hauptschlüssel an, der zum Verschlüsseln von Dateien verwendet wird. Der Hauptschlüssel muss ein 128-Bit- oder 256-Bit-Schlüssel in Base64-codierter Form sein.

Optionale Parameter

FILE_FORMAT = ( FORMAT_NAME = 'Dateiformatname' ) oder . FILE_FORMAT = ( TYPE = CSV | JSON | PARQUET [ ... ] )

Gibt das Format der Datendateien an, die entladene Daten enthalten:

FORMAT_NAME = 'Dateiformatname'

Gibt ein bestehendes benanntes Dateiformat an, das zum Entladen von Daten aus der Tabelle verwendet werden soll. Das benannte Dateiformat bestimmt den Formattyp (CSV, JSON, PARQUET) sowie alle anderen Formatoptionen für die Datendateien. Weitere Informationen finden Sie unter CREATE FILE FORMAT.

TYPE = CSV | JSON | PARQUET [ ... ]

Gibt den Typ der aus der Tabelle entladenen Dateien an.

Wenn ein Formattyp angegeben ist, können zusätzliche formatspezifische Optionen angegeben werden. Weitere Informationen dazu finden Sie unter Formattypoptionen (unter diesem Thema).

Bemerkung

  • JSON kann nur zum Entladen von Daten aus Spalten vom Typ VARIANT (d. h. Spalten mit JSON-Daten) verwendet werden.

  • Derzeit können verschachtelte Daten in VARIANT-Spalten nicht erfolgreich in ein Parquet-Format entladen werden.

copyOptions

Gibt eine oder mehrere Kopieroptionen für die entladenen Daten an. Weitere Details dazu finden Sie unter Kopieroptionen (unter diesem Thema).

HEADER = TRUE | FALSE

Gibt an, ob die Spaltenüberschriften der Tabelle in die Ausgabedateien aufgenommen werden sollen.

  • Setzen Sie diese Option auf TRUE, um die Tabellenspaltenüberschriften in die Ausgabedateien aufzunehmen.

    Beachten Sie, dass die Spaltenüberschriften in jeder Datei enthalten sind, wenn die COPY-Operation die Daten in mehrere Dateien entlädt.

    Beim Entladen von Daten im Parquet-Format bleiben die Tabellenspaltennamen in den Ausgabedateien erhalten.

  • Setzen Sie diese Option auf FALSE, um das folgende Verhalten anzugeben:

    CSV

    Kein Einfügen von Tabellenspaltenüberschriften in die Ausgabedateien.

    Parquet

    Einfügen von generischen Spaltenüberschriften (z. B. col1, col2 usw.) in die Ausgabedateien.

Standard: FALSE

Formattypoptionen (formatTypeOptions)

Je nach angegebenem Dateiformattyp (FILE_FORMAT = ( TYPE = ... )) können Sie eine oder mehrere der folgenden formatspezifischen Optionen (durch Leerzeichen, Kommas oder Neue-Zeile-Zeichen getrennt) einschließen:

TYPE = CSV

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

Zeichenfolge (Konstante), die angibt, dass die entladenen Datendateien unter Verwendung des angegebenen Komprimierungsalgorithmus komprimiert werden sollen.

Unterstützte Werte

Anmerkungen

AUTO

Entladene Dateien werden automatisch mit der Standardmethode gzip komprimiert.

GZIP

BZ2

BROTLI

Muss beim Laden von Brotli-komprimierten Dateien verwendet werden.

ZSTD

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

DEFLATE

Entladene Dateien werden mit Deflate (mit zlib-Header, RFC1950) komprimiert.

RAW_DEFLATE

Entladene Dateien werden mit Raw Deflate (ohne Header, RFC1951) komprimiert.

NONE

Entladene Dateien werden nicht komprimiert.

Standard: AUTO

RECORD_DELIMITER = 'Zeichen' | NONE

Ein oder mehrere Einzelbyte- oder Multibyte-Zeichen, die Datensätze in einer Eingabedatei (Laden von Daten) oder einer entladenen Datei (Entladen von Daten) voneinander trennen.

Akzeptiert gängige Escape-Sequenzen, Oktalwerte (mit \\ vorangestellt) oder Hex-Werte (mit 0x vorangestellt). Geben Sie beispielsweise für Datensätze, die durch das Thornzeichen (Þ) getrennt sind, den Oktalwert (\\336) oder den Hexadezimalwert (0xDE) an. Akzeptiert auch den Wert NONE.

Das angegebene Trennzeichen muss ein gültiges UTF-8-Zeichen sein und darf keine zufällige Folge von Bytes sein.

Trennzeichen mit mehreren Zeichen werden ebenfalls unterstützt. Das Trennzeichen für RECORD_DELIMITER oder FIELD_DELIMITER darf jedoch keine Teilzeichenfolge des Trennzeichens der anderen Dateiformatoption sein (z. B. FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). Das Trennzeichen darf maximal 20 Zeichen lang sein. Geben Sie keine Zeichen an, die für andere Dateiformatoptionen wie ESCAPE oder ESCAPE_UNENCLOSED_FIELD verwendet werden.

Standard: Neue-Zeile-Zeichen (\n).

FIELD_DELIMITER = 'Zeichen' | NONE

Ein oder mehrere Einzelbyte- oder Multibyte-Zeichen, die Felder in einer Eingabedatei (Laden von Daten) oder einer entladenen Datei (Entladen von Daten) voneinander trennen.

Akzeptiert gängige Escape-Sequenzen, Oktalwerte (mit \\ vorangestellt) oder Hex-Werte (mit 0x vorangestellt). Geben Sie beispielsweise für Felder, die durch das Thornzeichen (Þ) getrennt sind, den Oktalwert (\\336) oder den Hexadezimalwert (0xDE) an. Akzeptiert auch den Wert NONE.

Das angegebene Trennzeichen muss ein gültiges UTF-8-Zeichen sein und darf keine zufällige Folge von Bytes sein.

Trennzeichen mit mehreren Zeichen werden ebenfalls unterstützt. Das Trennzeichen für RECORD_DELIMITER oder FIELD_DELIMITER darf jedoch keine Teilzeichenfolge des Trennzeichens der anderen Dateiformatoption sein (z. B. FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). Das Trennzeichen darf maximal 20 Zeichen lang sein. Geben Sie keine Zeichen an, die für andere Dateiformatoptionen wie ESCAPE oder ESCAPE_UNENCLOSED_FIELD verwendet werden.

Standard: Komma (,)

FILE_EXTENSION = 'Zeichenfolge' | NONE

Zeichenfolge, die die Erweiterung für Dateien angibt, die in einen Stagingbereich entladen werden. Akzeptiert jede Erweiterung. Der Benutzer ist dafür verantwortlich, eine gültige Dateiendung anzugeben, die von der gewünschten Software oder dem gewünschten Service gelesen werden kann.

Bemerkung

Wenn die SINGLE-Kopieroption TRUE ist, wird mit dem Befehl COPY standardmäßig eine Datei ohne Dateiendung entladen. Um eine Dateierweiterung anzugeben, geben Sie einen Dateinamen und eine Erweiterung im Pfad interner_Speicherplatz oder externer_Speicherplatz an. Beispiel:

copy into @stage/data.csv ...

Standard: Null, d. h. die Dateierweiterung wird durch den Formattyp bestimmt, z. B. .csv[Komprimierung], wobei Komprimierung die durch die Komprimierungsmethode hinzugefügte Erweiterung ist, wenn COMPRESSION festgelegt ist.

DATE_FORMAT = 'Zeichenfolge' | AUTO

Zeichenfolge, die das Format von Datumswerten in den entladenen Datendateien definiert. Wenn ein Wert nicht angegeben oder auf AUTO gesetzt ist, wird der Wert für den Parameter DATE_OUTPUT_FORMAT verwendet.

Standard: AUTO

TIME_FORMAT = 'Zeichenfolge' | AUTO

Zeichenfolge, die das Format der Zeitwerte in den entladenen Datendateien definiert. Wenn ein Wert nicht angegeben oder auf AUTO gesetzt ist, wird der Wert für den Parameter TIME_OUTPUT_FORMAT verwendet.

Standard: AUTO

TIMESTAMP_FORMAT = 'Zeichenfolge' | AUTO

Zeichenfolge, die das Format der Zeitstempelwerte in den entladenen Datendateien definiert. Wenn ein Wert nicht angegeben oder auf AUTO gesetzt ist, wird der Wert für den Parameter TIMESTAMP_OUTPUT_FORMAT verwendet.

Standard: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

Zeichenfolge (Konstante), die das Codierungsformat für die Binärausgabe definiert. Die Option kann beim Entladen von Daten aus binären Spalten in einer Tabelle verwendet werden.

Standard: HEX

ESCAPE = 'Zeichen' | NONE
Verwendung

Laden und Entladen von Daten

Definition

Zeichenfolge mit einem einzelnen Zeichen, das als Escapezeichen für Feldwerte verwendet wird. Ein Escapezeichen ruft eine alternative Interpretation für nachfolgende Zeichen in einer Zeichenfolge auf. Sie können das ESCAPE-Zeichen verwenden, um Instanzen von FIELD_DELIMITER- oder RECORD_DELIMITER-Zeichen oder von FIELD_OPTIONALLY_ENCLOSED_BY-Zeichen in den Daten als Literale zu interpretieren. Das Escapezeichen kann auch verwendet werden, um Instanzen von sich selbst in den Daten in Escapezeichen einzuschließen.

Akzeptiert gängige Escapesequenzen, Oktalwerte oder Hexadezimalwerte.

Geben Sie mit FIELD_OPTIONALLY_ENCLOSED_BY das Zeichen an, mit dem Felder umschlossen werden sollen.

Wenn diese Option gesetzt ist, wird der Escapezeichensatz für ESCAPE_UNENCLOSED_FIELD überschrieben.

Standard

NONE

ESCAPE_UNENCLOSED_FIELD = 'Zeichen' | NONE
Verwendung

Laden und Entladen von Daten

Definition

Zeichenfolge mit einem einzelnen Zeichen, das als Escapezeichen nur für nicht eingeschlossene Feldwerte verwendet wird. Ein Escapezeichen ruft eine alternative Interpretation für nachfolgende Zeichen in einer Zeichenfolge auf. Sie können das ESCAPE-Zeichen verwenden, um Instanzen von FIELD_DELIMITER- oder RECORD_DELIMITER-Zeichen in den Daten als Literale zu interpretieren. Das Escapezeichen kann auch verwendet werden, um Instanzen von sich selbst in den Daten in Escapezeichen einzuschließen.

Akzeptiert gängige Escapesequenzen, Oktalwerte oder Hexadezimalwerte.

Wenn ESCAPE gesetzt ist, wird diese Option vom Escapezeichensatz der Dateiformatoption überschrieben.

Standard

Backslash (\\)

FIELD_OPTIONALLY_ENCLOSED_BY = 'Zeichen' | NONE

Zeichen, das verwendet wird, um Zeichenfolgen einzuschließen. Der Wert kann NONE, ein einfaches Anführungszeichen (') oder ein doppeltes Anführungszeichen (") sein. Um das einfache Anführungszeichen verwenden zu können, müssen Sie die oktale oder hexadezimale Darstellung (0x27) oder das doppelte einfache Anführungszeichen als Escape-Zeichen ('') verwenden.

Wenn ein Feld dieses Zeichen enthält, können Sie es mit dem gleichen Zeichen löschen. Wenn der Wert beispielsweise das doppelte Anführungszeichen ist und ein Feld die Zeichenfolge A "B" C enthält, schließen Sie die doppelten Anführungszeichen in Escapezeichen ein:

A ""B"" C

Standard: NONE

NULL_IF = ( 'Zeichenfolge1' [ , 'Zeichenfolge2' ... ] )

Zeichenfolge, die zum Konvertieren von SQL NULL verwendet wird: Snowflake konvertiert SQL-NULL-Werte in den ersten Wert der Liste.

Standard: \\N (d. h. NULL unter der Annahme ESCAPE_UNENCLOSED_FIELD=\\)

EMPTY_FIELD_AS_NULL = TRUE | FALSE

Wird in Kombination mit FIELD_OPTIONALLY_ENCLOSED_BY verwendet. Wenn FIELD_OPTIONALLY_ENCLOSED_BY = NONE festgelegt ist, werden bei EMPTY_FIELD_AS_NULL = FALSE leere Zeichenfolgen in Tabellen entladen, um leere Zeichenfolgenwerte zu erhalten, ohne dass die Feldwerte in Anführungszeichen gesetzt werden.

Wenn TRUE festgelegt wird, muss FIELD_OPTIONALLY_ENCLOSED_BY ein Zeichen angeben, das zum Umschließen von Zeichenfolgen verwendet wird.

Standard: TRUE

TYPE = JSON

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

Zeichenfolge (Konstante). Komprimiert die Datendatei unter Verwendung des angegebenen Komprimierungsalgorithmus.

Unterstützte Werte

Anmerkungen

AUTO

Entladene Dateien werden automatisch mit der Standardmethode gzip komprimiert.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Entladene Dateien werden mit Deflate (mit zlib-Header, RFC1950) komprimiert.

RAW_DEFLATE

Entladene Dateien werden mit Raw Deflate (ohne Header, RFC1951) komprimiert.

NONE

Entladene Dateien werden nicht komprimiert.

Standard: AUTO

FILE_EXTENSION = 'Zeichenfolge' | NONE

Zeichenfolge, die die Erweiterung für Dateien angibt, die in einen Stagingbereich entladen werden. Akzeptiert jede Erweiterung. Der Benutzer ist dafür verantwortlich, eine gültige Dateiendung anzugeben, die von der gewünschten Software oder dem gewünschten Service gelesen werden kann.

Standard: Null, d. h. die Dateierweiterung wird durch den Formattyp bestimmt (z. B. .csv[Komprimierung]), wobei Komprimierung die von der Komprimierungsmethode hinzugefügte Erweiterung ist, wenn COMPRESSION festgelegt ist.

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE

Zeichenfolge (Konstante). Komprimiert die Datendatei unter Verwendung des angegebenen Komprimierungsalgorithmus.

Unterstützte Werte

Anmerkungen

AUTO

Dateien werden mit dem Standardkomprimierungsalgorithmus Snappy komprimiert.

LZO

Dateien werden standardmäßig mit dem Snappy-Algorithmus komprimiert. Wenn Sie stattdessen die Lempel-Ziv-Oberhumer-Komprimierung (LZO) anwenden möchten, geben Sie diesen Wert an.

SNAPPY

Dateien werden standardmäßig mit dem Snappy-Algorithmus komprimiert. Sie können diesen Wert optional angeben.

NONE

Zeigt beim Entladen von Daten an, dass die entladenen Dateien nicht komprimiert werden.

Standard: AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

Boolescher Wert, der angibt, ob die entladenen Dateien mit dem SNAPPY-Algorithmus komprimiert werden.

Bemerkung

Veraltet. Verwenden Sie stattdessen COMPRESSION = SNAPPY.

Standard: TRUE

Kopieroptionen (copyOptions)

Sie können eine oder mehrere der folgenden Kopieroptionen angeben (durch Leerzeichen, Kommas oder Neue-Zeile-Zeichen getrennt):

OVERWRITE = TRUE | FALSE

Boolescher Wert, der angibt, ob der COPY-Befehl vorhandene Dateien, die am vorgesehenen Speicherort unter demselben Namen gespeichert sind, überschreiben soll. Mit dieser Option werden keine vorhandenen Dateien entfernt, deren Namen nicht mit den Namen der Dateien übereinstimmen, die mit dem COPY-Befehl entladen werden.

Standard: FALSE

SINGLE = TRUE | FALSE

Boolescher Wert, der angibt, ob eine einzelne Datei oder mehrere Dateien generiert werden sollen. Bei FALSE muss ein Dateinamenpräfix im Pfad enthalten sein.

Standard: FALSE

Wichtig

Wenn SINGLE = TRUE, dann ignoriert COPY die Dateiformatoption FILE_EXTENSION und gibt eine Datei mit dem einfachen Namen data aus. Um eine Dateierweiterung anzugeben, geben Sie im internen oder externen Speicherort Pfad einen Dateinamen und eine Erweiterung an. Beispiel:

COPY INTO @mystage/data.csv ...

Wenn außerdem die Dateiformatoption COMPRESSION explizit auf einen der unterstützten Komprimierungsalgorithmen (z. B. GZIP) festgelegt ist, muss der angegebene Pfad zum internen oder externen Speicherort mit einem Dateinamen und der entsprechenden Dateierweiterung (z. B. gz) enden, damit die Datei mit dem entsprechenden Tool dekomprimiert werden kann. Beispiel:

COPY INTO @mystage/data.gz ...

COPY INTO @mystage/data.csv.gz ...
MAX_FILE_SIZE = Zahl

Zahl (>0), die die maximale Größe (in Byte) jeder Datei angibt, die parallel pro Thread generiert werden soll. Beachten Sie, dass die tatsächliche Dateigröße und Anzahl der entladenen Dateien von der Gesamtdatenmenge und Anzahl der für die Parallelverarbeitung verfügbaren Knoten abhängt.

Snowflake nutzt die parallele Ausführung zur Leistungsoptimierung. Die Anzahl der Threads kann nicht geändert werden.

Standardeinstellung: 16000000 (16 MB)

Maximum: 5 GB (Amazon S3-, Google Cloud Storage- oder Microsoft Azure-Stagingbereich).

Bemerkung

Mit dem COPY-Befehl wird jeweils immer ein Satz von Tabellenzeilen entladen. Wenn Sie einen sehr kleinen MAX_FILE_SIZE-Wert festlegen, kann die Datenmenge in einem Satz von Zeilen die angegebene Größe überschreiten.

INCLUDE_QUERY_ID = TRUE | FALSE

Boolescher Wert, der angibt, ob entladene Dateien eindeutig identifiziert werden sollen, indem ein universell eindeutiger Bezeichner (UUID) in die Dateinamen entladener Datendateien eingefügt wird. Mit dieser Option wird sichergestellt, dass gleichzeitige COPY-Anweisungen nicht versehentlich zu Überschreiben entladener Dateien führen.

Wenn TRUE, wird den Namen der entladenen Dateien eine UUID hinzugefügt. Die UUID ist die Abfrage-ID der COPY-Anweisung, die zum Entladen der Datendateien verwendet wird. Die UUID ist ein Segment des Dateinamens: <Pfad>/data_<UUID>_<Name>.<Erweiterung>.

Wenn FALSE, wird den Namen der entladenen Datendateien keine UUID hinzugefügt.

Standard: FALSE

Bemerkung

INCLUDE_QUERY_ID = TRUE wird nicht unterstützt, wenn eine der folgenden Kopieroptionen festgelegt ist:

  • SINGLE = TRUE

  • OVERWRITE = TRUE

DETAILED_OUTPUT = TRUE | FALSE

Boolescher Wert, der angibt, ob die Befehlsausgabe den Entladeoperation oder die einzelnen Dateien beschreiben soll, die als Ergebnis der Operation entladen wurden.

Bei TRUE enthält die Befehlsausgabe eine Zeile für jede Datei, die in den angegebenen Stagingbereich entladen wurde. In den Spalten werden Pfad und Name jeder Datei, deren Größe und die Anzahl der Zeilen angezeigt, die in die Datei entladen wurden. Bei FALSE besteht die Befehlsausgabe aus einer einzelnen Zeile, die die gesamte Entladeoperation beschreibt. In den Spalten werden die Gesamtmenge der aus Tabellen entladenen Daten vor und nach der Komprimierung (falls zutreffend) sowie die Gesamtzahl der entladenen Zeilen angezeigt.

Standard: FALSE

Nutzungshinweise

  • STORAGE_INTEGRATION oder CREDENTIALS gelten nur, wenn Daten direkt in einen privaten Speicherort (Amazon S3, Google Cloud Storage oder Microsoft Azure) entladen werden. Wenn Daten in einen öffentlichen Bucket entladen werden, ist kein sicherer Zugriff erforderlich. Wenn Daten in einen benannten externen Stagingbereich entladen werden, liefert der Stagingbereich alle Anmeldeinformationen, die für den Zugriff auf den Bucket erforderlich sind.

  • Wenn Sie ein Dateiformat im aktuellen Namespace referenzieren, können Sie die einfachen Anführungszeichen um den Formatbezeichner herum weglassen.

  • JSON kann für TYPE nur beim Entladen von Daten aus VARIANT-Spalten in Tabellen angegeben werden.

  • Beim Entladen in Dateien des Typs PARQUET:

    • VARIANT-Spalten werden in der Ausgabedatei in einfache JSON-Zeichenfolgen umgewandelt.

    • Das Entladen von TIMESTAMP_TZ- oder TIMESTAMP_LTZ-Daten führt zu einem Fehler.

  • Wenn die Quelltabelle 0 Zeilen enthält, dann wird mit der COPY-Operation keine Datendatei entladen.

  • Eine fehlgeschlagene COPY-Anweisung kann weiterhin dazu führen, dass Daten entladen werden, so zum Beispiel wenn die Anweisung das Zeitlimit überschreitet und abgebrochen wird.

  • Wenn für eine Spalte eine Sicherheit auf Spaltenebene-Maskierungsrichtlinie festgelegt ist, wird die Maskierungsrichtlinie auf die Daten angewendet, sodass nicht autorisierten Benutzern maskierte Daten in der Spalte angezeigt werden.

Beispiele

Entladen von Daten aus einer Tabelle in Dateien eines Tabellen-Stagingbereichs

Entladen Sie Daten aus der orderstiny-Tabelle in den Tabellen-Stagingbereich unter Verwendung eines Präfixes für Ordner/Dateinamen (result/data_), eines benannten Dateiformats (myformat) und einer gzip-Komprimierung:

COPY INTO @%orderstiny/result/data_
  FROM orderstiny FILE_FORMAT = (FORMAT_NAME ='myformat' COMPRESSION='GZIP');

Entladen von Daten aus einer Abfrage in Dateien eines benannten internen Stagingbereichs

Entladen Sie das Ergebnis einer Abfrage in einen benannten internen Stagingbereich (my_stage) unter Verwendung eines Präfixes für Ordner/Dateinamen (result/data_), eines benannten Dateiformats (myformat) und einer gzip-Komprimierung:

COPY INTO @my_stage/result/data_ FROM (SELECT * FROM orderstiny)
   file_format=(format_name='myformat' compression='gzip');

Beachten Sie, dass das obige Beispiel funktional dem ersten Beispiel entspricht, mit der Ausnahme, dass die Datei mit den entladenen Daten im Stagingbereichsspeicherort für my_stage und nicht am Tabellenspeicherort für orderstiny gespeichert wird.

Entladen von Daten aus einer Tabelle direkt in Dateien an einem externen Speicherort

Entladen Sie alle Daten einer Tabelle an einen Speicherort mithilfe eines benannten my_csv_format-Dateiformats:

Amazon S3

Greifen Sie auf den referenzierten S3-Bucket mittels einer referenzierten Speicherintegration namens myint zu:

COPY INTO 's3://mybucket/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Greifen Sie mit den angegebenen Anmeldeinformationen auf den referenzierten S3-Bucket zu:

COPY INTO 's3://mybucket/unload/'
  FROM mytable
  CREDENTIALS = (AWS_KEY_ID='xxxx' AWS_SECRET_KEY='xxxxx' AWS_TOKEN='xxxxxx')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Google Cloud Storage

Greifen Sie mit einer referenzierten Speicherintegration namens myint auf den referenzierten GCS-Bucket zu:

COPY INTO 'gcs://mybucket/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Microsoft Azure

Greifen Sie auf den referenzierten Container mittels einer referenzierten Speicherintegration namens myint zu:

COPY INTO 'azure://myaccount.blob.core.windows.net/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Greifen Sie mit den bereitgestellten Anmeldeinformationen auf den referenzierten Container zu:

COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/unload/'
  FROM mytable
  CREDENTIALS=(AZURE_SAS_TOKEN='xxxx')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Beibehalten von NULL-/leeren Felddaten in entladenen Dateien

Behalten Sie SQL NULL und leere Felder in entladenen Dateien bei:

-- View the table column values

select * from HOME_SALES;

+------------+-------+-------+-------------+--------+-----------+
| CITY       | STATE | ZIP   | TYPE        | PRICE  | SALE_DATE |
|------------+-------+-------+-------------+--------+-----------|
| Lexington  | MA    | 95815 | Residential | 268880 | 3/28/17   |
| Belmont    | MA    | 95815 | Residential |        | 2/21/17   |
| Winchester | MA    | NULL  | Residential |        | 1/31/17   |
+------------+-------+-------+-------------+--------+-----------+

-- Unload the table data into the current user's personal stage. The file format options retain both the NULL value and the empty values in the output file

copy into @~ from HOME_SALES
file_format=(type=csv null_if = ('NULL', 'null')
empty_field_as_null=false);

-- Contents of the output file

95815,MA-Lexington,268880,3/28/17
95815,MA-Belmont,,2/21/17
NULL,MA-Winchester,389921,1/31/17

Entladen von Daten in eine einzelne Datei

Entladen Sie alle Zeilen in eine einzelne Datendatei mit der Kopieroption SINGLE:

copy into @~ from HOME_SALES
single = true;

Einfügen der UUID in die Namen entladener Dateien

Fügen Sie die UUID in die Namen entladener Dateien ein, indem Sie die Kopieroption INCLUDE_QUERY_ID auf TRUE setzen:

-- Unload rows from the T1 table into the T1 table stage:
COPY INTO @%t1
  FROM t1
  FILE_FORMAT=(TYPE=parquet)
  INCLUDE_QUERY_ID=true;

-- Retrieve the query ID for the COPY INTO location statement.
-- This optional step enables you to see that the query ID for the COPY INTO location statement
-- is identical to the UUID in the unloaded files.
SELECT last_query_id();
+--------------------------------------+
| LAST_QUERY_ID()                      |
|--------------------------------------|
| 019260c2-00c0-f2f2-0000-4383001cf046 |
+--------------------------------------+

LS @%t1;
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+
| name                                                           | size | md5                              | last_modified                 |
|----------------------------------------------------------------+------+----------------------------------+-------------------------------|
| data_019260c2-00c0-f2f2-0000-4383001cf046_0_0_0.snappy.parquet |  544 | eb2215ec3ccce61ffa3f5121918d602e | Thu, 20 Feb 2020 16:02:17 GMT |
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+

Validierung der zu entladenden Daten (aus einer Abfrage)

Führen Sie COPY im Validierungsmodus aus, um das Ergebnis einer Abfrage zurückzugeben und die Daten anzuzeigen, die aus der orderstiny-Tabelle entladen werden, wenn COPY im Normalmodus ausgeführt wird:

COPY INTO @my_stage
FROM (SELECT * FROM orderstiny LIMIT 5)
VALIDATION_MODE='RETURN_ROWS';

----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+
 C1 |   C2   | C3 |    C4     |     C5     |    C6    |       C7        | C8 |                                    C9                                     |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+
 1  | 36901  | O  | 173665.47 | 1996-01-02 | 5-LOW    | Clerk#000000951 | 0  | nstructions sleep furiously among                                         |
 2  | 78002  | O  | 46929.18  | 1996-12-01 | 1-URGENT | Clerk#000000880 | 0  |  foxes. pending accounts at the pending\, silent asymptot                 |
 3  | 123314 | F  | 193846.25 | 1993-10-14 | 5-LOW    | Clerk#000000955 | 0  | sly final accounts boost. carefully regular ideas cajole carefully. depos |
 4  | 136777 | O  | 32151.78  | 1995-10-11 | 5-LOW    | Clerk#000000124 | 0  | sits. slyly regular warthogs cajole. regular\, regular theodolites acro   |
 5  | 44485  | F  | 144659.20 | 1994-07-30 | 5-LOW    | Clerk#000000925 | 0  | quickly. bold deposits sleep slyly. packages use slyly                    |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+