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>

Syntax

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

Wobei:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
Copy
externalStage ::=
  @[<namespace>.]<ext_stage_name>[/<path>]
Copy
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' ] ) ]
Copy
externalLocation (for Google Cloud Storage) ::=
  'gcs://<bucket>[/<path>]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]
Copy
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>' ] ) ]
Copy
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 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     FILE_EXTENSION = '<string>'
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | LZO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
Copy
copyOptions ::=
     OVERWRITE = TRUE | FALSE
     SINGLE = TRUE | FALSE
     MAX_FILE_SIZE = <num>
     INCLUDE_QUERY_ID = TRUE | FALSE
     DETAILED_OUTPUT = TRUE | FALSE
Copy

Erforderliche Parameter

INTO ...

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

@[namespace.]int_stage_name[/path]

Dateien werden in den angegebenen benannten internen Stagingbereich entladen.

@[namespace.]ext_stage_name[/path]

Die Dateien werden in den angegebenen benannten externen Stagingbereich entladen.

@[namespace.]%table_name[/path]

Die Dateien werden in den Stagingbereich der angegebenen Tabelle entladen.

@~[/path]

Die Dateien werden in den Stagingbereich des aktuellen Benutzers entladen.

's3://bucket[/path]'

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

'gcs://bucket[/path]'

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

'azure://account.blob.core.windows.net/container[/path]'

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 database_name.schema_name oder schema_name. Die Angabe ist optional, wenn in der Benutzersitzung aktuell eine Datenbank und ein Schema verwendet werden, andernfalls ist die Angabe obligatorisch.

  • Der optionale path-Parameter gibt ein Ordner- und Dateinamenspräfix für die Datei(en) an, die entladene Daten enthalten. Wenn ein Dateinamenpräfix nicht in path enthalten ist oder der Parameter PARTITION BY angegeben ist, enthalten die Dateinamen der generierten Datendateien das Präfix data_.

    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;
    
    -- Google Cloud Storage bucket
    COPY INTO 'gcs://mybucket/./../a.csv' FROM mytable;
    
    -- Azure container
    COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv' FROM mytable;
    
    Copy

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

Bemerkung

  • Wenn der Name des internen oder externen Stagingbereichs oder des Pfads Sonderzeichen, einschließlich Leerzeichen, enthält, schließen Sie die Zeichenfolge INTO ... in einfache Anführungszeichen ein.

  • Der Wert INTO ... muss eine literale Konstante sein. Der Wert kann keine SQL-Variable sein.

FROM ...

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

[namespace.]table_name

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 der Form database_name.schema_name oder schema_name an. Die Angabe ist optional, wenn in der Benutzersitzung aktuell eine Datenbank und ein Schema verwendet werden, andernfalls ist die Angabe obligatorisch.

( query )

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 = integration_name oder . CREDENTIALS = ( cloud_specific_credentials )

Wird unterstützt, wenn die COPY-Anweisung für den Ziel-Cloudspeicherort die URI eines externen Speicherplatzes und nicht den Namen eines externen Stagingbereiches angibt. 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 = integration_name

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 = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] ) oder . CREDENTIALS = ( AWS_ROLE = 'string' )

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 AWS IAM (Identity & Access Management)-Benutzer oder einer 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 dieses Feature verwenden, um stattdessen auf Speicherintegrationsobjekte zu verweisen. Eine Anleitung dazu finden Sie unter Option 1: Konfigurieren einer Snowflake-Speicherintegration für Zugriff auf Amazon S3.

Google Cloud Storage

STORAGE_INTEGRATION = integration_name

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

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 = 'string' )

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 = ( cloud_specific_encryption )

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.

  • NONE: Keine Verschlüsselung.

MASTER_KEY = 'string' (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 = 'string' (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' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )

TYPE = ...

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

KMS_KEY_ID = 'string' (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 = 'string' ] )

TYPE = ...

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

MASTER_KEY = 'string' (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

PARTITION BY expr

Gibt einen Ausdruck an, der zur Partitionierung der entladenen Tabellenzeilen in separate Dateien verwendet wird. Unterstützt jeden SQL-Ausdruck, der eine Zeichenfolge ausgibt.

Die Entladeoperation teilt die Tabellenzeilen auf der Grundlage des Partitionsausdrucks auf und bestimmt die Anzahl der zu erstellenden Dateien auf der Grundlage der Datenmenge und der Anzahl der parallelen Operationen, die auf die Computeressourcen im Warehouse verteilt sind.

Dateinamen werden mit dem Präfix data_ versehen und enthalten die Werte der Partitionsspalten. Einzelne Dateinamen in jeder Partition werden mit einem universell eindeutigen Bezeichner (UUID) identifiziert. Die UUID ist die Abfrage-ID der COPY-Anweisung, die zum Entladen der Datendateien verwendet wird.

Vorsicht

Mit COPY INTO <Speicherort>-Anweisungen werden Partitionsspaltenwerte in die benannten entladenen Dateien geschrieben. Wir empfehlen eindringlich, Ihre Daten auf gängige Datentypen wie Datumsangaben oder Zeitstempel zu partitionieren und nicht auf potenziell sensible Zeichenfolgen- oder Ganzzahl-Werte.

Beachten Sie, dass die Datei-URLs in den internen Protokollen enthalten sind, die Snowflake zur Unterstützung der Fehlersuche führt, wenn Kunden Supportfälle erstellen. Dadurch werden Daten in Spalten, auf die in einem PARTITION BY-Ausdruck verwiesen wird, indirekt auch in internen Protokollen gespeichert. Diese Protokolle werden möglicherweise außerhalb Ihrer Bereitstellungsregion verarbeitet. Daher sollten Sie als bewährte Methode nur Datumsangaben, Zeitstempel und boolesche Datentypen in PARTITION BY-Ausdrücke aufnehmen.

Wenn Sie es vorziehen, den PARTITION BY-Parameter in COPY INTO <Speicherort>-Anweisungen für Ihr Konto deaktivieren möchten, wenden Sie sich an den Snowflake-Support.

Beachten Sie, dass Snowflake eine Reihe von Parametern zur weiteren Einschränkung von Datenentladeoperationen bereitstellt:

  • PREVENT_UNLOAD_TO_INLINE_URL gibt an, ob Ad-hoc-Operationen zum Entladen von Daten an externe Cloudspeicherorte verhindert werden sollen (d. h. COPY INTO <Speicherort>-Anweisungen, die die Cloudspeicher-URL angeben und direkt in der Anweisung auf Einstellungen zugreifen).

  • PREVENT_UNLOAD_TO_INTERNAL_STAGES verhindert Datenentladeoperationen in beliebige interne Stagingbereiche, einschließlich Benutzer-, Tabellen- oder benannte interne Stagingbereiche.

Ein Beispiel dazu finden Sie unter Partitionieren entladener Zeilen in Parquet-Dateien (unter diesem Thema).

Bemerkung

  • Die folgenden Werte für Kopieroptionen können nicht in Kombination mit PARTITION BY verwendet werden:

    • OVERWRITE = TRUE

    • SINGLE = TRUE

    • INCLUDE_QUERY_ID = FALSE

  • Das Einbeziehen der ORDER BY-Klausel in die SQL-Anweisung in Kombination mit PARTITION BY garantiert nicht, dass die angegebene Reihenfolge in den entladenen Dateien erhalten bleibt.

  • Wenn der PARTITION BY-Ausdruck den Wert NULL ergibt, lautet der Partitionspfad im Ausgabedateinamen _NULL_ (z. B. mystage/_NULL_/data_01234567-0123-1234-0000-000000001234_01_0_0.snappy.parquet).

  • Beim Entladen in Dateien des Typs PARQUET:

    • Kleine Datendateien, die von parallelen Ausführungsthreads entladen werden, werden automatisch zu einer einzigen Datei zusammengeführt, die dem Wert der MAX_FILE_SIZE-Kopieroption so genau wie möglich entspricht.

    • Alle Zeilengruppen sind 128 MB groß. Eine Zeilengruppe ist eine logische horizontale Partitionierung der Daten in Zeilen. Es gibt keine physische Struktur, die für eine Zeilengruppe garantiert ist. Eine Zeilengruppe besteht aus einem Spaltenblock für jede Spalte des Datasets.

    • Bei der Entladeoperation wird versucht, Dateien zu erstellen, deren Größe der Einstellung der MAX_FILE_SIZE-Kopieroption so nahe wie möglich kommt. Der Standardwert für diese Kopieroption ist 16 MB. Beachten Sie, dass dieses Verhalten nur beim Entladen von Daten in Parquet-Dateien zutrifft.

    • VARIANT-Spalten werden in einfache JSON-Zeichenfolgen umgewandelt. Die Umwandlung der Werte in ein Array (mit der Funktion TO_ARRAY) ergibt ein Array mit JSON-Zeichenfolgen.

  • Es gibt keine Option, um die Spalten im Partitionsausdruck aus den entladenen Datendateien wegzulassen.

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

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

FORMAT_NAME = 'file_format_name'

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

VALIDATION_MODE = RETURN_ROWS

Zeichenfolge (Konstante), die den COPY-Befehl anweist, die Ergebnisse der Abfrage in der SQL-Anweisung zurückzugeben und nicht in den angegebenen Cloudspeicherort zu entladen. Die einzige unterstützte Validierungsoption ist RETURN_ROWS. Diese Option gibt alle von der Abfrage erzeugten Zeilen zurück.

Wenn Sie die Abfrage validiert haben, können Sie VALIDATION_MODE entfernen, um die Entladeoperation auszuführen.

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/Entladen von Brotli-komprimierten Dateien angegeben 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 = 'character' | NONE

Ein oder mehrere Einzelbyte- oder Multibyte-Zeichen, die Datensätze in einer entladenen Datei voneinander trennen. Akzeptiert gängige Escapesequenzen oder die folgenden Einzelbyte- oder Multibyte-Zeichen:

Einzelbyte-Zeichen:

Oktalwerte (mit \\ vorangestellt) oder Hexadezimalwerte (mit 0x oder \x vorangestellt). Geben Sie beispielsweise für Datensätze, die durch das Zirkumflex-Akzentzeichen (^) getrennt sind, den Oktalwert (\\136) oder den Hexadezimalwert (0x5e) an.

Multibyte-Zeichen:

Hexadezimalwerte (mit vorangestelltem \x). Geben Sie beispielsweise für Datensätze, die durch das Centzeichen (¢) getrennt sind, den Hexadezimalwert (\xC2\xA2) an.

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 angegebene Trennzeichen muss ein gültiges UTF-8-Zeichen sein und darf keine zufällige Sequenz von Bytes sein. Beachten Sie auch, dass das Trennzeichen nur maximal 20 Zeichen lang sein darf.

Akzeptiert auch den Wert NONE.

Standard: Neue-Zeile-Zeichen. Beachten Sie, dass „neue Zeile“ logisch ist, sodass \r\n als neue Zeile für Dateien auf einer Windows-Plattform verstanden wird.

FIELD_DELIMITER = 'character' | NONE

Ein oder mehrere Einzelbyte- oder Multibyte-Zeichen, die Felder in einer entladenen Datei voneinander trennen. Akzeptiert gängige Escapesequenzen oder die folgenden Einzelbyte- oder Multibyte-Zeichen:

Einzelbyte-Zeichen:

Oktalwerte (mit \\ vorangestellt) oder Hexadezimalwerte (mit 0x oder \x vorangestellt). Geben Sie beispielsweise für Datensätze, die durch das Zirkumflex-Akzentzeichen (^) getrennt sind, den Oktalwert (\\136) oder den Hexadezimalwert (0x5e) an.

Multibyte-Zeichen:

Hexadezimalwerte (mit vorangestelltem \x). Geben Sie beispielsweise für Datensätze, die durch das Centzeichen (¢) getrennt sind, den Hexadezimalwert (\xC2\xA2) an.

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').

Bemerkung

Für Nicht-ASCII-Zeichen müssen Sie den Hex-Byte-Sequenzwert verwenden, um ein deterministisches Verhalten zu erreichen.

Das angegebene Trennzeichen muss ein gültiges UTF-8-Zeichen sein und darf keine zufällige Sequenz von Bytes sein. Beachten Sie auch, dass das Trennzeichen nur maximal 20 Zeichen lang sein darf.

Akzeptiert auch den Wert NONE.

Standard: Komma (,)

FILE_EXTENSION = 'string' | 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 Kopieroption SINGLE den Wert TRUE hat, 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 zum internen Speicherplatz internal_location oder im Pfad zum externen Speicherplatz external_location an. Beispiel:

copy into @stage/data.csv ...

Standard: Null, d. h. die Dateierweiterung wird durch den Formattyp bestimmt, z. B. .csv[compression], wobei compression die von der Kompressionsmethode hinzugefügte Erweiterung ist, wenn COMPRESSION gesetzt ist.

DATE_FORMAT = 'string' | 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 = 'string' | 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 = 'string' | 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 = 'character' | NONE
Verwendung:

Laden und Entladen von Daten

Definition:

Zeichenfolge mit einem Einzelbyte-Zeichen, das als Escapezeichen für eingeschlossene und nicht eingeschlossene Feldwerte verwendet wird. Ein Escapezeichen ruft eine alternative Interpretation für nachfolgende Zeichen in einer Sequenz von Zeichen auf. Sie können das ESCAPE-Zeichen verwenden, um Instanzen 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 = 'character' | NONE
Verwendung:

Laden und Entladen von Daten

Definition:

Zeichenfolge mit Einzelbyte-Zeichen, das als Escapezeichen nur für nicht eingeschlossene Feldwerte verwendet wird. Ein Escapezeichen ruft eine alternative Interpretation für nachfolgende Zeichen in einer Sequenz von Zeichen 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 = 'character' | 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 = ( 'string1' [ , 'string2' ... ] )

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 = 'string' | 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[compression]), wobei compression die von der Kompressionsmethode hinzugefügte Erweiterung ist, wenn COMPRESSION gesetzt 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
Definition:

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.

In vielen Fällen hilft das Aktivieren dieser Option, das Duplizieren von Daten in den Stagingbereich zu verhindern, wenn dieselbe COPY INTO <Speicherort>-Anweisung mehrfach ausgeführt wird. Wenn jedoch eine Entladeoperation mehrere Dateien in einen Stagingbereich schreibt, fügt Snowflake ein Suffix hinzu, das sicherstellt, dass jeder Dateiname über parallele Ausführungsthreads hinweg eindeutig ist (z. B. data_0_1_0). Die Anzahl der parallelen Ausführungsthreads kann zwischen den Entladeoperationen variieren. Wenn die durch einen Entladeoperation geschriebenen Dateien nicht die gleichen Dateinamen haben wie die durch eine vorherige Operation geschriebenen Dateien, können SQL-Anweisungen, die diese Kopieroption enthalten, die vorhandenen Dateien nicht ersetzen, was zu duplizierten Dateien führt.

Im seltenen Fall eines Computer- oder Netzwerkausfalls wird außerdem die Ausführung des Entlade-Jobs erneut versucht. In diesem Szenario werden durch die Entladeoperation zusätzliche Dateien in den Stagingbereich geschrieben, ohne dass erst alle Dateien entfernt werden, die im ersten Versuch geschrieben wurden.

Um eine Datenduplizierung im Ziel-Stagingbereich zu vermeiden, empfehlen wir, dass die Kopieroption INCLUDE_QUERY_ID = TRUE anstelle von OVERWRITE = TRUE eingestellt wird und dass zwischen jedem Entlade-Job alle Datendateien im Ziel-Stagingbereich und im Pfad entfernt werden (oder bei jeder Entladeoperation ein anderer Pfad verwendet wird).

Standard:

FALSE

SINGLE = TRUE | FALSE
Definition:

Boolescher Wert, der angibt, ob eine einzelne Datei oder mehrere Dateien generiert werden sollen. Wenn FALSE, muss in path ein Dateinamen-Präfix enthalten sein.

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 path einen Dateinamen und eine Erweiterung an. Beispiel:

COPY INTO @mystage/data.csv ...
Copy

Wenn außerdem die Dateiformatoption COMPRESSION explizit auf einen der unterstützten Komprimierungsalgorithmen (z. B. GZIP) eingestellt ist, muss der angegebene interne oder externe Speicherort-path in einem Dateinamen mit der entsprechenden Dateiendung (z. B. gz) enden, damit die Datei mit dem entsprechenden Werkzeug entpackt werden kann. Beispiel:

COPY INTO @mystage/data.gz ...

COPY INTO @mystage/data.csv.gz ...
Copy
Standard:

FALSE

MAX_FILE_SIZE = num
Definition:

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.

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 der Datenumfang einer Menge von Zeilen die angegebene Größe überschreiten.

Standard:

16777216 (16 MB)

INCLUDE_QUERY_ID = TRUE | FALSE
Definition:

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 zum Überschreiben entladener Dateien führen.

Werte:

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.

Bemerkung

  • INCLUDE_QUERY_ID = TRUE ist der Standardwert der Kopieroption, wenn Sie die entladenen Tabellenzeilen in separate Dateien partitionieren (durch Setzen von PARTITION BY expr in der COPY INTO <Speicherort>-Anweisung). Dieser Wert kann nicht in FALSE geändert werden.

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

    • SINGLE = TRUE

    • OVERWRITE = TRUE

  • Im seltenen Fall eines Computer- oder Netzwerkausfalls wird außerdem die Ausführung des Entlade-Jobs erneut versucht. In diesem Szenario werden durch die Entladeoperation alle Dateien entfernt, die mit der aktuellen Abfrage-ID als UUID in den Stagingbereich geschrieben wurden, und danach wird versucht, die Daten erneut zu entladen. Die UUID aller neuen Dateien, die in den Stagingbereich geschrieben werden, ist die ID der wiederholten Abfrage.

Standard:

FALSE

DETAILED_OUTPUT = TRUE | FALSE
Definition:

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

Werte:
  • 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 CSV, JSON oder PARQUET:

    VARIANT-Spalten werden in der Ausgabedatei standardmäßig in einfache JSON-Zeichenfolgen umgewandelt.

    • Um die Daten als Parquet-LIST-Werte zu entladen, wandeln Sie die Spaltenwerte explizit in Arrays um (mit der Funktion TO_ARRAY).

    • Wenn eine VARIANT-Spalte XML-Code enthält, empfehlen wir, die Spaltenwerte in einer FROM ...-Abfrage explizit auf XML umzuwandeln. Beim Umwandeln der Werte mit der Funktion TO_XML werden XML-formatierte Zeichenfolgen anstelle von JSON-Zeichenfolgen entladen.

  • Beim Entladen in Dateien des Typs PARQUET:

    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.

  • Dieser SQL-Befehl gibt keine Warnung zurück, wenn in einen nicht leeren Speicherplatz entladen wird. Um unerwartetes Verhalten zu vermeiden, wenn Dateien an einem Speicherort von Datenpipelines genutzt werden, empfehlen wir, nur in leere Speicherorte zu schreiben.

  • Eine fehlgeschlagene Entladeoperation kann weiterhin dazu führen, dass Datendateien entladen werden, so zum Beispiel wenn die Anweisung das Timeout überschreitet und abgebrochen wird. Auch eine fehlgeschlagene Entladeoperation auf Cloudspeicher in einer anderen Region führt zu Datenübertragungskosten.

  • Wenn für eine Spalte eine 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');
Copy

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

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

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

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

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

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

Partitionieren entladener Zeilen in Parquet-Dateien

Im folgenden Beispiel werden Zeilen in Parquet-Dateien nach Werten in zwei Spalten partitioniert: einer Datumsspalte und einer Uhrzeitspalte. Das Beispiel gibt eine maximale Größe für jede entladene Datei an:

CREATE or replace TABLE t1 (
  dt date,
  ts time
  )
AS
  SELECT TO_DATE($1)
        ,TO_TIME($2)
    FROM VALUES
           ('2020-01-28', '18:05')
          ,('2020-01-28', '22:57')
          ,('2020-01-28', NULL)
          ,('2020-01-29', '02:15')
;

SELECT * FROM t1;

+------------+----------+
| DT         | TS       |
|------------+----------|
| 2020-01-28 | 18:05:00 |
| 2020-01-28 | 22:57:00 |
| 2020-01-28 | 22:32:00 |
| 2020-01-29 | 02:15:00 |
+------------+----------+

-- Partition the unloaded data by date and hour. Set ``32000000`` (32 MB) as the upper size limit of each file to be generated in parallel per thread.
COPY INTO @%t1
  FROM t1
  PARTITION BY ('date=' || to_varchar(dt, 'YYYY-MM-DD') || '/hour=' || to_varchar(date_part(hour, ts))) -- Concatenate labels and column values to output meaningful filenames
  FILE_FORMAT = (TYPE=parquet)
  MAX_FILE_SIZE = 32000000
  HEADER=true;

LIST @%t1;

+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+
| name                                                                                     | size | md5                              | last_modified                |
|------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------|
| __NULL__/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet                |  512 | 1c9cb460d59903005ee0758d42511669 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=18/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet |  592 | d3c6985ebb36df1f693b52c4a3241cc4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=22/data_019c059d-0502-d90c-0000-438300ad6596_006_6_0.snappy.parquet |  592 | a7ea4dc1a8d189aabf1768ed006f7fb4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-29/hour=2/data_019c059d-0502-d90c-0000-438300ad6596_006_0_0.snappy.parquet  |  592 | 2d40ccbb0d8224991a16195e2e7e5a95 | Wed, 5 Aug 2020 16:58:16 GMT |
+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+
Copy

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 | 2017-03-28 |
| Belmont    | MA    | 95815 | Residential |        | 2017-02-21 |
| Winchester | MA    | NULL  | Residential |        | 2017-01-31 |
+------------+-------+-------+-------------+--------+------------+

-- 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
Lexington,MA,95815,Residential,268880,2017-03-28
Belmont,MA,95815,Residential,,2017-02-21
Winchester,MA,NULL,Residential,,2017-01-31
Copy

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

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

Validieren 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                    |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+
Copy