Catégories :

Commandes DML - Déchargement des données

COPY INTO <emplacement>

Décharge les données d’une table (ou d’une requête) dans un ou plusieurs fichiers à l’un des emplacements suivants :

  • Zone de préparation interne nommée (ou zone de préparation de table/utilisateur). Les fichiers peuvent ensuite être téléchargés à partir de la zone de préparation/emplacement à l’aide de la commande GET.

  • Zone de préparation externe nommée qui fait référence à un emplacement externe (Amazon S3, Google Cloud Storage ou Microsoft Azure).

  • Emplacement externe (Amazon S3, Google Cloud Storage ou Microsoft Azure).

Voir aussi :

COPY INTO <table>

Dans ce chapitre :

Syntaxe

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 ]

Où :

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

Paramètres requis

INTO ...

Indique l’emplacement interne ou externe dans lequel les fichiers de données sont déchargés :

@[espace_noms.]nom_zone_de_préparation_interne[/chemin]

Les fichiers sont déchargés dans la zone de préparation interne spécifiée.

@[espace_noms.]nom_zone_de_préparation_externe[/chemin]

Les fichiers sont déchargés dans la zone de préparation externe spécifiée.

@[espace_noms.]%nom_table[/chemin]

Les fichiers sont déchargés dans la zone de préparation de la table spécifiée.

@~[/chemin]

Les fichiers sont déchargés dans la zone de préparation pour l’utilisateur courant.

's3://compartiment[/chemin]'

Les fichiers sont déchargés dans l’emplacement externe spécifié (compartiment S3). D’autres paramètres peuvent être nécessaires. Pour plus de détails, voir Paramètres supplémentaires de fournisseurs de Cloud (dans ce chapitre).

'azure://compte.blob.core.windows.net/conteneur[/chemin]'

Les fichiers sont déchargés dans l’emplacement externe spécifié (conteneur Azure). D’autres paramètres peuvent être nécessaires. Pour plus de détails, voir Paramètres supplémentaires de fournisseurs de Cloud (dans ce chapitre).

Où :

  • espace_noms est la base de données et/ou le schéma dans lequel réside la zone de préparation interne ou externe, sous la forme nom_basededonnées.nom_schéma ou nom_schéma. Il est facultatif si une base de données et un schéma sont actuellement utilisés dans la session utilisateur. Dans le cas contraire, il est nécessaire.

  • Le paramètre chemin facultatif spécifie un préfixe de dossier et de nom de fichier pour le(s) fichier(s) contenant des données déchargées. Si un préfixe de nom de fichier n’est pas inclus dans chemin, les noms de fichiers des fichiers de données générés sont préfixés avec data_.

    Les modificateurs de chemins d’accès relatifs tels que /./ et /../ sont interprétés littéralement, car les « chemins » sont des préfixes littéraux pour un nom. Par exemple :

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

    Dans ces instructions COPY, Snowflake crée un fichier littéralement nommé ./../a.csv dans l’emplacement de stockage.

Note

La chaîne URI d’un emplacement externe (c.-à-d. Amazon S3, Google Cloud Storage ou Microsoft Azure) doit être entourée de guillemets simples. Cependant, vous pouvez inclure n’importe quelle chaîne entre guillemets simples, ce qui permet l’insertion de caractères spéciaux, y compris des espaces, dans les noms de fichier et de lieu. Par exemple :

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

Indique la source des données à décharger, qui peut être une table ou une requête :

[espace_noms.]nom_table

Indique le nom de la table à partir de laquelle les données sont déchargées.

L’espace de noms spécifie facultativement la base de données et/ou le schéma dans lesquels la table réside, sous la forme nom_basededonnées.nom_schéma ou nom_schéma. Il est facultatif si une base de données et un schéma sont actuellement utilisés dans la session utilisateur. Dans le cas contraire, il est nécessaire.

( requête )

Instruction SELECT qui renvoie les données à décharger dans les fichiers. Vous pouvez limiter le nombre de lignes renvoyées en spécifiant une clause LIMIT / FETCH dans la requête.

Note

Lors de la conversion de valeurs de colonne en un type de données à l’aide de la fonction CAST , ::, vérifiez que le type de données prend en charge toutes les valeurs de colonne. Des valeurs trop longues pour le type de données spécifié pourraient être tronquées.

Paramètres supplémentaires du fournisseur de Cloud

STORAGE_INTEGRATION = nom_intégration ou . CREDENTIALS = ( identifiants_Cloud_spécifiques )

À utiliser dans les instructions COPY ad hoc (instructions qui ne font pas référence à une zone de préparation externe nommée). Spécifie les identifiants de connexion de sécurité pour la connexion au fournisseur de Cloud et l’accès au conteneur de stockage privé dans lequel les fichiers déchargés sont mis en zone de préparation.

Requis uniquement pour le déchargement dans un emplacement de stockage dans le Cloud privé externe ; non requis pour les compartiments/conteneurs publics

Amazon S3

STORAGE_INTEGRATION = nom_intégration

Spécifie le nom de l’intégration de stockage utilisée pour déléguer la responsabilité de l’authentification pour le stockage en Cloud externe à une entité Gestion des identités et des accès Snowflake (IAM). Pour plus de détails, voir CREATE STORAGE INTEGRATION.

Note

Nous recommandons fortement l’utilisation d’intégrations de stockage. Cette option évite d’avoir à fournir des informations d’identification de stockage Cloud à l’aide du paramètre CREDENTIALS lors de la création de zones de préparation ou du chargement de données.

CREDENTIALS = ( AWS_KEY_ID = 'chaîne' AWS_SECRET_KEY = 'chaîne' [ AWS_TOKEN = 'chaîne' ] ) ou . CREDENTIALS = ( AWS_ROLE = 'chaîne' )

Spécifie les identifiants de connexion de sécurité pour se connecter à AWS et accéder au compartiment S3 privé dans lequel les fichiers déchargés sont mis en zone de préparation. Pour plus d’informations, voir Configuration de l’accès sécurisé à Amazon S3.

Les informations d’identification que vous spécifiez varient selon que vous avez associé les autorisations d’accès Snowflake au compartiment à un utilisateur AWS IAM (Identity & Access Management) ou à un rôle :

  • Utilisateur IAM : des informations d’identification IAM temporaires sont requises. Les informations d’identification temporaires (alias « étendues ») sont générées par le service d’émission de jeton de sécurité AWS (STS) et se composent de trois éléments :

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    Tous les trois sont nécessaires pour accéder à un compartiment privé. Au bout d’une certaine période de temps, les identifiants de connexion temporaires expirent et ne peuvent plus être utilisés. Vous devez ensuite générer un nouvel ensemble d’informations d’identification temporaires valides.

    Important

    Les commandes COPY contiennent une syntaxe complexe et des informations sensibles, telles que des informations d’identification. De plus, elles sont exécutées fréquemment et sont souvent stockées dans des scripts ou des feuilles de calcul, ce qui peut entraîner la divulgation accidentelle d’informations sensibles. La commande COPY permet d’utiliser des informations d’identification permanentes (alias « à long terme ») ; cependant, pour des raisons de sécurité, n’utilisez pas d’informations d’identification permanentes dans les commandes COPY. Utilisez plutôt des identifiants temporaires.

    Si vous devez utiliser des informations d’identification permanentes, utilisez des zone de préparation externes, pour lesquelles les informations d’identification sont saisies une seule fois et stockées en toute sécurité, ce qui réduit au minimum le risque d’exposition.

  • Rôle IAM : n’indiquez pas d’identifiants de sécurité et de clés d’accès et, à la place, identifiez le rôle en utilisant AWS_ROLE et spécifiez le rôle AWS ARN (Amazon Resource Name).

    Important

    La possibilité d’utiliser un rôle IAM AWS pour accéder à un compartiment S3 privé pour charger ou décharger des données est désormais obsolète (c’est-à-dire que la prise en charge sera supprimée dans une prochaine version, à déterminer). Nous vous recommandons vivement de modifier toutes les zones de préparation S3 existantes qui utilisent cette fonctionnalité pour référencer à la place des objets d’intégration de stockage. Pour obtenir des instructions, voir Option 1 : Configuration d’une intégration de stockage Snowflake.

Google Cloud Storage

STORAGE_INTEGRATION = nom_intégration

Spécifie le nom de l’intégration de stockage utilisée pour déléguer la responsabilité de l’authentification pour le stockage en Cloud externe à une entité Gestion des identités et des accès Snowflake (IAM). Pour plus de détails, voir CREATE STORAGE INTEGRATION.

Microsoft Azure

STORAGE_INTEGRATION = nom_intégration

Spécifie le nom de l’intégration de stockage utilisée pour déléguer la responsabilité de l’authentification pour le stockage en Cloud externe à une entité Gestion des identités et des accès Snowflake (IAM). Pour plus de détails, voir CREATE STORAGE INTEGRATION.

Note

Nous recommandons fortement l’utilisation d’intégrations de stockage. Cette option évite d’avoir à fournir des informations d’identification de stockage Cloud à l’aide du paramètre CREDENTIALS lors de la création de zones de préparation ou du chargement de données.

CREDENTIALS = ( AZURE_SAS_TOKEN = 'chaîne' )

Spécifie le jeton de signature d’accès partagé (SAS) pour se connecter à Azure et accéder au conteneur privé dans lequel les fichiers contenant des données sont mis en zone de préparation. Les identifiants de connexion sont générés par Azure.

ENCRYPTION = ( chiffrement_spécifique_cloud )

À utiliser dans les instructions COPY ad hoc (instructions qui ne font pas référence à une zone de préparation externe nommée). Requis uniquement pour décharger des données dans des fichiers dans des emplacements de stockage chiffrés

Amazon S3

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

TYPE = ...

Indique le type de chiffrement utilisé. Les valeurs possibles sont les suivantes :

  • AWS_CSE : chiffrement côté client (nécessite une valeur MASTER_KEY). Actuellement, la clé maître côté client que vous fournissez ne peut être qu’une clé symétrique. Notez que, lorsqu’une valeur MASTER_KEY est fournie, Snowflake part du principe que TYPE = AWS_CSE (plus précisément, lorsqu’une valeur MASTER_KEY est fournie, TYPE n’est pas nécessaire).

  • AWS_SSE_S3 : chiffrement côté serveur qui ne nécessite aucun paramètre de chiffrement supplémentaire.

  • AWS_SSE_KMS : chiffrement côté serveur qui accepte une valeur KMS_KEY_ID facultative.

Pour plus d’informations sur les types de chiffrement, voir la documentation AWS pour le chiffrement côté client ou le chiffrement côté serveur.

MASTER_KEY = 'chaîne' (s’applique uniquement au chiffrement AWS_CSE)

Spécifie la clé maître côté client qui a été utilisée pour chiffrer les fichiers dans le compartiment. La clé maître doit être une clé de 128 ou 256 bits codée en Base64.

KMS_KEY_ID = 'chaîne' (s’applique uniquement au chiffrement AWS_SSE_KMS)

Spécifie éventuellement l’ID de la clé AWS gérée par KMS qui est utilisée pour chiffrer les fichiers déchargés dans le compartiment. Si aucune valeur n’est fournie, l’ID de votre clé KMS par défaut est utilisé pour chiffrer les fichiers au déchargement.

Notez que cette valeur est ignorée pour le chargement des données.

Google Cloud Storage

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

TYPE = ...

Indique le type de chiffrement utilisé. Les valeurs possibles sont les suivantes :

  • GCS_SSE_KMS : chiffrement côté serveur qui accepte une valeur KMS_KEY_ID facultative.

Pour plus d’informations, consultez la documentation de Google Cloud Platform :

KMS_KEY_ID = 'chaîne' (s’applique uniquement au chiffrement GCS_SSE_KMS)

Spécifie éventuellement l’ID de la clé gérée par Cloud KMS qui est utilisée pour chiffrer les fichiers déchargés dans le compartiment. Si aucune valeur n’est fournie, l’ID de votre clé KMS par défaut est utilisé pour chiffrer les fichiers au déchargement.

Notez que cette valeur est ignorée pour le chargement des données. L’opération de chargement doit réussir si le compte de service dispose des autorisations suffisantes pour déchiffrer les données dans le compartiment.

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | NONE ] [ MASTER_KEY = 'chaîne' ] )

TYPE = ...

Indique le type de chiffrement utilisé. Les valeurs possibles sont les suivantes :

  • AZURE_CSE : chiffrement côté client (nécessite une valeur MASTER_KEY). Pour plus d’informations, voir les informations de chiffrement côté client dans la documentation Microsoft Azure.

  • NONE : pas de chiffrement.

MASTER_KEY = 'chaîne' (s’applique uniquement au chiffrement AZURE_CSE)

Spécifie la clé maître côté client utilisée pour chiffrer les fichiers. La clé maître doit être une clé de 128 ou 256 bits codée en Base64.

Paramètres facultatifs

FILE_FORMAT = ( FORMAT_NAME = 'nom_format_fichier' ) ou . FILE_FORMAT = ( TYPE = CSV | JSON | PARQUET [ ... ] )

Spécifie le format des fichiers de données contenant des données non chargées :

FORMAT_NAME = 'nom_format_fichier'

Spécifie un format de fichier nommé existant à utiliser pour décharger les données de la table. Le format de fichier nommé détermine le type de format (CSV, JSON, PARQUET), ainsi que toute autre option de format, pour les fichiers de données. Pour plus d’informations, voir CREATE FILE FORMAT.

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

Spécifie le type de fichiers déchargés de la table.

Si un type de format est spécifié, des options supplémentaires spécifiques au format peuvent être spécifiées. Pour plus d’informations, voir les Options de type de format (dans cette rubrique).

Note

  • JSON ne peut être utilisé que pour décharger les données des colonnes de type VARIANT (c’est-à-dire les colonnes contenant des données JSON).

  • Actuellement, les données imbriquées dans les colonnes VARIANT ne peuvent pas être déchargées avec succès au format Parquet.

copyOptions

Spécifie une ou plusieurs options de copie pour les données déchargées. Pour plus de détails, voir Options de copie (dans cette rubrique).

HEADER = TRUE | FALSE

Indique s’il faut inclure les en-têtes de colonnes de la table dans les fichiers de sortie.

  • Définissez cette option sur TRUE pour inclure les en-têtes de colonnes de la table dans les fichiers de sortie.

    Notez que si l’opération COPY décharge les données dans plusieurs fichiers, les en-têtes de colonnes sont inclus dans tous les fichiers.

    Lors du déchargement des données au format Parquet, les noms des colonnes de table sont conservés dans les fichiers de sortie.

  • Définissez cette option sur FALSE pour spécifier le comportement suivant :

    CSV

    N’incluez pas les en-têtes de colonnes dans les fichiers de sortie.

    Parquet

    Incluez des en-têtes de colonnes génériques (par exemple, col1, col2, etc.) dans les fichiers de sortie.

Par défaut : FALSE

Options de type de format (formatTypeOptions)

En fonction du type de format de fichier spécifié (FILE_FORMAT = ( TYPE = ... )), vous pouvez inclure une ou plusieurs des options suivantes, spécifiques au format (séparées par des espaces, des virgules ou de nouvelles lignes) :

TYPE = CSV

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

Chaîne (constante) qui spécifie la compression des fichiers de données déchargés en utilisant l’algorithme de compression spécifié.

Valeurs prises en charge

Remarques

AUTO

Les fichiers déchargés sont automatiquement compressés en utilisant la valeur par défaut, qui est gzip.

GZIP

BZ2

BROTLI

Doit être utilisé si vous chargez des fichiers compressés Brotli.

ZSTD

Zstandard v0.8 (et supérieur) est pris en charge.

DEFLATE

Les fichiers déchargés sont compressés en utilisant Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Les fichiers déchargés sont compressés à l’aide de Raw Deflate (sans en-tête, RFC1951).

NONE

Les fichiers déchargés ne sont pas compressés.

Par défaut : AUTO

RECORD_DELIMITER = 'caractère' | NONE

Un ou plusieurs caractères à un octet ou à plusieurs octets qui séparent les enregistrements dans un fichier d’entrée (chargement de données) ou un fichier déchargé (déchargement de données).

Accepte les séquences d’échappement courantes, les valeurs octales (préfixées par \\) ou les valeurs hexadécimales (préfixées par 0x). Par exemple, pour les enregistrements délimités par le caractère thorn (Þ), spécifiez la valeur octale (\\336) ou hexadécimale (0xDE). Accepte également une valeur de NONE.

Le délimiteur spécifié doit être un caractère UTF-8 valide et non une séquence aléatoire d’octets.

Les délimiteurs à plusieurs caractères sont également pris en charge ; cependant, le délimiteur pour RECORD_DELIMITER ou FIELD_DELIMITER ne peut pas être une sous-chaîne du délimiteur pour l’autre option de format de fichier (par exemple FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). Le délimiteur est limité à un maximum de 20 caractères. Ne spécifiez pas les caractères utilisés pour les autres options de format de fichier, tels que ESCAPE ou ESCAPE_UNENCLOSED_FIELD.

Par défaut : caractère de nouvelle ligne (\n).

FIELD_DELIMITER = 'caractère' | NONE

Un ou plusieurs caractères à un octet ou à plusieurs octets qui séparent les champs d’un fichier d’entrée (chargement de données) ou d’un fichier déchargé (déchargement de données).

Accepte les séquences d’échappement courantes, les valeurs octales (préfixées par \\) ou les valeurs hexadécimales (préfixées par 0x). Par exemple, pour les champs délimités par le caractère thorn (Þ), spécifiez la valeur octale (\\336) ou hexadécimale (0xDE). Accepte également une valeur de NONE.

Le délimiteur spécifié doit être un caractère UTF-8 valide et non une séquence aléatoire d’octets.

Les délimiteurs à plusieurs caractères sont également pris en charge ; cependant, le délimiteur pour RECORD_DELIMITER ou FIELD_DELIMITER ne peut pas être une sous-chaîne du délimiteur pour l’autre option de format de fichier (par exemple FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'). Le délimiteur est limité à un maximum de 20 caractères. Ne spécifiez pas les caractères utilisés pour les autres options de format de fichier, tels que ESCAPE ou ESCAPE_UNENCLOSED_FIELD.

Valeur par défaut : virgule (,)

FILE_EXTENSION = 'chaîne' | NONE

Chaîne qui spécifie l’extension des fichiers déchargés dans une zone de préparation. Accepte toute extension. L’utilisateur est chargé de spécifier une extension de fichier valide qui peut être lue par tout logiciel ou service souhaité.

Note

Si l’option de copie SINGLE est TRUE, alors la commande COPY décharge un fichier sans extension par défaut. Pour spécifier une extension de fichier, fournissez un nom et une extension de fichier dans le chemin emplacement_interne ou emplacement_externe. Par exemple :

copy into @stage/data.csv ...

Valeur : Null, ce qui signifie que l’extension du fichier est déterminée par le type de format, par exemple : .csv[compression], où compression est l’extension ajoutée par la méthode de compression, si COMPRESSION est défini.

DATE_FORMAT = 'chaîne' | AUTO

Chaîne qui définit le format des valeurs de dates dans des fichiers de données déchargés. Si une valeur n’est pas spécifiée ou est réglée sur AUTO, la valeur du paramètre DATE_OUTPUT_FORMAT est utilisée.

Par défaut : AUTO

TIME_FORMAT = 'chaîne' | AUTO

Chaîne qui définit le format des valeurs temporelles dans les fichiers de données déchargés. Si une valeur n’est pas spécifiée ou est réglée sur AUTO, la valeur du paramètre TIME_OUTPUT_FORMAT est utilisée.

Par défaut : AUTO

TIMESTAMP_FORMAT = 'chaîne' | AUTO

Chaîne qui définit le format des valeurs d’horodatage dans les fichiers de données déchargés. Si une valeur n’est pas spécifiée ou est réglée sur AUTO, la valeur du paramètre TIMESTAMP_OUTPUT_FORMAT est utilisée.

Par défaut : AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

Chaîne (constante) qui définit le format d’encodage de la sortie binaire. L’option peut être utilisée pour décharger des données à partir de colonnes binaires dans une table.

Par défaut : HEX

ESCAPE = 'caractère' | NONE
Utilisation

Chargement et déchargement des données

Définition

Chaîne d’un caractère unique utilisée comme caractère d’échappement pour les valeurs de champ. Un caractère d’échappement appelle une autre interprétation sur les caractères suivants dans une séquence de caractères. Vous pouvez utiliser le caractère ESCAPE pour interpréter les instances des caractères FIELD_DELIMITER, RECORD_DELIMITER ou FIELD_OPTIONALLY_ENCLOSED_BY dans les données comme des littéraux. Le caractère d’échappement peut également être utilisé pour échapper les instances de lui-même dans les données.

Accepte les séquences d’échappement, les valeurs octales ou les valeurs hexadécimales courantes.

Spécifiez le caractère utilisé pour délimiter les champs en définissant FIELD_OPTIONALLY_ENCLOSED_BY.

Si cette option est activée, elle remplace le jeu de caractères d’échappement pour ESCAPE_UNENCLOSED_FIELD.

Par défaut

NONE

ESCAPE_UNENCLOSED_FIELD = 'caractère' | NONE
Utilisation

Chargement et déchargement des données

Définition

Chaîne d’un caractère unique utilisée comme caractère d’échappement pour les valeurs de champs non délimitées uniquement. Un caractère d’échappement appelle une autre interprétation sur les caractères suivants dans une séquence de caractères. Vous pouvez utiliser le caractère ESCAPE pour interpréter les instances des caractères FIELD_DELIMITER ou RECORD_DELIMITER dans les données comme des littéraux. Le caractère d’échappement peut également être utilisé pour échapper les instances de lui-même dans les données.

Accepte les séquences d’échappement, les valeurs octales ou les valeurs hexadécimales courantes.

Si ESCAPE est défini, le jeu de caractères d’échappement pour cette option de format de fichier l’emporte sur cette option.

Par défaut

barre oblique inverse (\\)

FIELD_OPTIONALLY_ENCLOSED_BY = 'caractère' | NONE

Caractère utilisé pour délimiter des chaînes. La valeur peut être NONE, un caractère guillemet simple (') ou un caractère guillemet double ("). Pour utiliser le caractère guillemet simple, utilisez la représentation octale ou hexadécimale (0x27) ou le double échappement en guillemet simple ('').

Lorsqu’un champ contient ce caractère, effectuez un échappement en utilisant le même caractère. Par exemple, si la valeur est le caractère de guillemet double et qu’un champ contient la chaîne A "B" C, effectuez un échappement des guillemets doubles comme suit :

A ""B"" C

Par défaut : NONE

NULL_IF = ( 'chaîne1' [ , 'chaîne2' ... ] )

Chaîne utilisée pour effectuer une conversion depuis SQL NULL. Snowflake convertit les valeurs SQL NULL vers la première valeur de la liste.

Par défaut : \\N (c.-à-d. NULL, en supposant que ESCAPE_UNENCLOSED_FIELD=\\)

EMPTY_FIELD_AS_NULL = TRUE | FALSE

Utilisé en combinaison avec FIELD_OPTIONALLY_ENCLOSED_BY. Lorsque FIELD_OPTIONALLY_ENCLOSED_BY = NONE, le paramètre EMPTY_FIELD_AS_NULL = FALSE spécifie de décharger les chaînes vides dans les tables pour vider les valeurs de chaîne sans guillemets entourant les valeurs de champ.

S’il est défini sur TRUE, FIELD_OPTIONALLY_ENCLOSED_BY doit spécifier un caractère pour entourer les chaînes.

Par défaut : TRUE

TYPE = JSON

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

Chaîne (constante). Compresse le fichier de données en utilisant l’algorithme de compression spécifié.

Valeurs prises en charge

Remarques

AUTO

Les fichiers déchargés sont automatiquement compressés en utilisant la valeur par défaut, qui est gzip.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Les fichiers déchargés sont compressés en utilisant Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Les fichiers déchargés sont compressés à l’aide de Raw Deflate (sans en-tête, RFC1951).

NONE

Les fichiers déchargés ne sont pas compressés.

Par défaut : AUTO

FILE_EXTENSION = 'chaîne' | NONE

Chaîne qui spécifie l’extension des fichiers déchargés dans une zone de préparation. Accepte toute extension. L’utilisateur est chargé de spécifier une extension de fichier valide qui peut être lue par tout logiciel ou service souhaité.

Valeur : Null, ce qui signifie que l’extension du fichier est déterminée par le type de format (par exemple, .csv[compression]), où compression est l’extension ajoutée par la méthode de compression, si COMPRESSION est défini.

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE

Chaîne (constante). Compresse le fichier de données en utilisant l’algorithme de compression spécifié.

Valeurs prises en charge

Remarques

AUTO

Les fichiers sont compressés à l’aide de Snappy, l’algorithme de compression par défaut.

LZO

Les fichiers sont compressés à l’aide de l’algorithme Snappy par défaut. Si vous appliquez la compression Lempel–Ziv–Oberhumer (LZO) à la place, spécifiez cette valeur.

SNAPPY

Les fichiers sont compressés à l’aide de l’algorithme Snappy par défaut. Vous pouvez spécifier cette valeur en option.

NONE

Spécifie que les fichiers déchargés ne sont pas compressés.

Par défaut : AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

Booléen qui spécifie si les fichiers déchargés sont compressés en utilisant l’algorithme SNAPPY.

Note

Obsolète. Utilisez plutôt COMPRESSION = SNAPPY.

Par défaut : TRUE

Options de copie (copyOptions)

Vous pouvez spécifier une ou plusieurs des options de copie suivantes (séparées par des espaces, des virgules ou de nouvelles lignes) :

OVERWRITE = TRUE | FALSE

Booléen qui spécifie si la commande COPY écrase les fichiers existants avec les noms correspondants, le cas échéant, à l’emplacement où les fichiers sont stockés. L’option ne supprime pas les fichiers existants qui ne correspondent pas aux noms des fichiers déchargés par la commande COPY.

Par défaut : FALSE

SINGLE = TRUE | FALSE

Booléen qui spécifie s’il faut générer un seul fichier ou plusieurs fichiers. Si FALSE, un préfixe de nom de fichier doit être inclus dans le chemin.

Par défaut : FALSE

Important

Si SINGLE = TRUE, alors COPY ignore l’option de format de fichier FILE_EXTENSION et affiche un fichier simplement nommé data. Pour spécifier une extension de fichier, indiquez un nom et une extension de fichier dans le chemin de l’emplacement interne ou externe. Par exemple :

COPY INTO @mystage/data.csv ...

En outre, si l’option de format de fichier COMPRESSION est également explicitement définie sur l’un des algorithmes de compression pris en charge (par exemple, GZIP), le chemin de l’emplacement interne ou externe spécifié doit se terminer par un nom de fichier portant l’extension correspondante (par exemple, gz) afin que le fichier puisse être décompressé avec l’outil approprié. Par exemple :

COPY INTO @mystage/data.gz ...

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

Numéro (> 0) qui spécifie la taille maximale (en octets) de chaque fichier à générer en parallèle par thread. Notez que la taille de fichier réelle et le nombre de fichiers déchargés sont déterminés par la quantité totale de données et le nombre de nœuds disponibles pour le traitement en parallèle.

Snowflake utilise l’exécution parallèle pour optimiser les performances. Le nombre de threads ne peut pas être modifié.

Par défaut : 16000000 (16 MB)

Maximum : 5 GB (zone de préparation Amazon S3 , Google Cloud Storage ou Microsoft Azure)

Note

La commande COPY décharge un jeu de lignes de table à la fois. Si vous définissez une très petite valeur MAX_FILE_SIZE, la quantité de données dans un ensemble de lignes peut dépasser la taille spécifiée.

INCLUDE_QUERY_ID = TRUE | FALSE

Boolean qui spécifie s’il faut identifier de manière unique les fichiers déchargés en incluant un identifiant universellement unique (UUID) dans les noms de fichiers des fichiers de données déchargés. Cette option permet de garantir que les instructions COPY simultanées n’écrasent pas accidentellement les fichiers déchargés.

Si TRUE, un UUID est ajouté aux noms des fichiers déchargés. L’UUID est l’ID de requête de l’instruction COPY utilisée pour décharger les fichiers de données. L’UUID est un segment du nom de fichier : <chemin>/data_<uuid>_<nom>.<extension>.

Si FALSE, alors un UUID n’est pas ajouté aux fichiers de données déchargés.

Par défaut : FALSE

Note

INCLUDE_QUERY_ID = TRUE n’est pas pris en charge lorsque l’une des options de copie suivantes est définie :

  • SINGLE = TRUE

  • OVERWRITE = TRUE

DETAILED_OUTPUT = TRUE | FALSE

Boolean qui spécifie si la sortie de la commande doit décrire l’opération de déchargement ou les fichiers individuels déchargés à la suite de l’opération.

Si TRUE, la sortie de la commande comprend une ligne pour chaque fichier déchargé à la zone de préparation spécifiée. Les colonnes indiquent le chemin et le nom de chaque fichier, sa taille et le nombre de lignes qui ont été déchargées dans le fichier. Si FALSE, la sortie de la commande se compose d’une seule ligne qui décrit l’ensemble de l’opération de déchargement. Les colonnes indiquent la quantité totale de données déchargées des tables, avant et après la compression (le cas échéant), et le nombre total de lignes qui ont été déchargées.

Par défaut : FALSE

Notes sur l’utilisation

  • STORAGE_INTEGRATION ou CREDENTIALS ne s’applique que si vous effectuez les déchargements directement dans un emplacement de stockage privé (p. ex. Amazon S3, Google Cloud Storage ou Microsoft Azure). Si vous déchargez dans un compartiment public, aucun accès sécurisé n’est requis, et si vous déchargez dans une zone de préparation externe désignée, la zone de préparation fournit toutes les informations d’identification requises pour accéder au compartiment.

  • Si vous faites référence à un format de fichier dans l’espace de noms actuel, vous pouvez omettre les guillemets simples autour de l’identificateur de format.

  • JSON ne peut être spécifié pour TYPE que lors du déchargement des données de colonnes VARIANT dans des tables.

  • Lors du déchargement vers des fichiers de type PARQUET :

    • Les colonnes VARIANT sont converties en chaînes JSON simples dans le fichier de sortie.

    • Le déchargement des données TIMESTAMP_TZ ou TIMESTAMP_LTZ produit une erreur.

  • Si la table source contient 0 ligne, l’opération COPY ne décharge pas un fichier de données.

  • Une instruction COPY ayant échoué peut toujours entraîner le déchargement des fichiers de données ; par exemple, si l’instruction dépasse son délai d’expiration et est annulée.

  • Si une politique de masquage Sécurité au niveau des colonnes est définie sur une colonne, la politique de masquage est appliquée aux données, ce qui permet aux utilisateurs non autorisés de voir les données masquées dans la colonne.

Exemples

Déchargement des données d’une table vers des fichiers d’une zone de préparation de table

Déchargez les données de la table orderstiny dans la zone de préparation de la table en utilisant un préfixe de dossier/nom de fichier (result/data_), un format de fichier nommé (myformat), et une compression gzip :

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

Déchargement des données d’une requête vers des fichiers dans une zone de préparation interne nommée

Déchargez le résultat d’une requête dans une zone de préparation interne nommée (my_stage) en utilisant un préfixe de dossier/nom de fichier (result/data_), un format de fichier nommé (myformat), et une compression gzip :

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

Notez que l’exemple ci-dessus est fonctionnellement équivalent au premier exemple, sauf que le fichier contenant les données déchargées est stocké dans l’emplacement de zone de préparation my_stage plutôt que dans l’emplacement de table pour orderstiny.

Déchargement des données d’une table directement dans des fichiers d’un emplacement externe

Décharger toutes les données d’une table dans un emplacement de stockage à l’aide du format de fichier my_csv_format nommé :

Amazon S3

Accéder au compartiment S3 référencé à l’aide d’une intégration de stockage référencée nommée myint :

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

Accéder au compartiment S3 référencé à l’aide des identifications de connexion fournies :

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

Accéder au compartiment GCS référencé à l’aide d’une intégration de stockage référencée nommée myint :

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

Microsoft Azure

Accéder au conteneur référencé à l’aide d’une intégration de stockage référencée nommée myint :

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

Accéder au conteneur référencé à l’aide des informations d’identification fournies :

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

Conservation de données NULL/champs vides dans des fichiers déchargés

Conservez les champs SQL NULL et vides dans des fichiers déchargés :

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

Déchargement des données dans un fichier unique

Déchargez toutes les lignes dans un seul fichier de données en utilisant l’option de copie SINGLE :

copy into @~ from HOME_SALES
single = true;

Inclusion de l’UUID dans les noms de fichiers déchargés

Incluez l’UUID dans les noms des fichiers déchargés en définissant l’option de copie INCLUDE_QUERY_ID sur TRUE :

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

Validation des données à décharger (à partir d’une requête)

Exécuter COPY en mode Validation pour afficher les résultats d’une requête et visualiser les données qui seront déchargées de la table orderstiny si la commande COPY est exécutée en mode normal :

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