Catégories :

Commandes DML - Chargement des données

COPY INTO <table>

Charge les données de fichiers préparés dans une table existante. Les fichiers doivent déjà être préparés dans l’un des emplacements suivants :

  • Zone de préparation interne nommée (ou zone de préparation de table/utilisateur). Les fichiers peuvent être préparés à l’aide de la commande PUT.

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

Dans ce chapitre :

Syntaxe

/* Standard data load */
COPY INTO [<namespace>.]<table_name>
     FROM { internalStage | externalStage | externalLocation }
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_<n>_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS ]

/* Data load with transformation */
COPY INTO [<namespace>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
     FROM ( SELECT [<alias>.]$<file_col_num>[.<element>] [ , [<alias>.]$<file_col_num>[.<element>] ... ]
            FROM { internalStage | externalStage } )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_<n>_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS ]

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
     SKIP_HEADER = <integer>
     SKIP_BLANK_LINES = TRUE | FALSE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     TRIM_SPACE = TRUE | FALSE
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     VALIDATE_UTF8 = TRUE | FALSE
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     ENCODING = '<string>' | UTF8
-- If FILE_FORMAT = ( TYPE = JSON ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     ENABLE_OCTAL = TRUE | FALSE
     ALLOW_DUPLICATE = TRUE | FALSE
     STRIP_OUTER_ARRAY = TRUE | FALSE
     STRIP_NULL_VALUES = TRUE | FALSE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
-- If FILE_FORMAT = ( TYPE = AVRO ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = ORC ... )
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | SNAPPY | NONE
     BINARY_AS_TEXT = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If FILE_FORMAT = ( TYPE = XML ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     PRESERVE_SPACE = TRUE | FALSE
     STRIP_OUTER_ELEMENT = TRUE | FALSE
     DISABLE_SNOWFLAKE_DATA = TRUE | FALSE
     DISABLE_AUTO_CONVERT = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
copyOptions ::=
     ON_ERROR = { CONTINUE | SKIP_FILE | SKIP_FILE_<num> | SKIP_FILE_<num>% | ABORT_STATEMENT }
     SIZE_LIMIT = <num>
     PURGE = TRUE | FALSE
     RETURN_FAILED_ONLY = TRUE | FALSE
     MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
     ENFORCE_LENGTH = TRUE | FALSE
     TRUNCATECOLUMNS = TRUE | FALSE
     FORCE = TRUE | FALSE
     LOAD_UNCERTAIN_FILES = TRUE | FALSE

Paramètres requis

[espace_noms.]nom_table

Spécifie le nom de la table dans laquelle les données sont chargées.

L’espace de noms spécifie facultativement la base de données et/ou le schéma de la table, sous la forme de nom_base_de_donné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.

FROM ...

Indique l’emplacement interne ou externe dans lequel les fichiers contenant les données à charger sont préparés :

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

Les fichiers se trouvent dans la zone de préparation interne nommée spécifiée.

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

Les fichiers se trouvent dans la zone de préparation externe nommée spécifiée.

@[espace_noms.]%nom_table[/chemin]

Les fichiers sont préparés pour la table spécifiée.

@~[/chemin]

Les fichiers sont mis en zone de préparation pour l’utilisateur actuel.

's3://compartiment[/chemin]'

Les fichiers se trouvent dans l’emplacement externe spécifié (compartiment S3). Des paramètres supplémentaires peuvent être requis. 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 se trouvent dans l’emplacement externe spécifié (conteneur Azure). Des paramètres supplémentaires peuvent être requis. 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.

  • chemin est un chemin facultatif respectant la casse pour les fichiers dans l’emplacement de stockage Cloud (c’est-à-dire que les fichiers ont des noms qui commencent par une chaîne en commun) qui limite l’ensemble de fichiers à charger. Les chemins sont appelés préfixes ou dossiers selon les services de stockage Cloud.

    Les modificateurs de chemins 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 mytable FROM 's3://mybucket/./../a.csv';
    
    -- Azure container
    COPY INTO mytable FROM 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv';
    

    Dans ces instructions COPY, Snowflake recherche un fichier littéralement nommé ./../a.csv dans l’emplacement externe.

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 mytable FROM '@mystage/path 1/file 1.csv';
COPY INTO mytable FROM '@%mytable/path 1/file 1.csv';
COPY INTO mytable FROM '@~/path 1/file 1.csv';

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

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

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 informations d’identification de sécurité pour la connexion au fournisseur de Cloud et l’accès au conteneur de stockage privé/protégé dans lequel les fichiers de données sont mis en zone de préparation.

Requis uniquement pour le chargement depuis un emplacement de stockage dans le Cloud privé/protégé 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' ] )

Spécifie les informations d’identification de sécurité pour se connecter à AWS et accéder au compartiment S3 privé/protégé dans lequel les fichiers à charger/décharger sont préparés. 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é/protégé. Au bout d’un certain temps, les informations d’identification temporaires expirent et ne peuvent plus être utilisées. 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 identifiants de connexion permanents, utilisez des zones de préparation externes, pour lesquelles les identifiants de connexion sont saisis une seule fois et stockés en toute sécurité, ce qui réduit au minimum le risque d’exposition.

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é/protégé dans lequel les fichiers contenant des données sont préparés. Les informations d’identification sont générées 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). Nécessaire uniquement pour un chargement depuis des fichiers chiffrés ; inutile si les fichiers ne sont pas chiffrés. Spécifie les paramètres de chiffrement utilisés pour déchiffrer les fichiers chiffrés dans l’emplacement de stockage.

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 déchiffrer les fichiers. La clé maître doit être une clé de 128 ou 256 bits codée en Base64.

Paramètres de transformation

( SELECT [alias.]$num_col_fich[.élément] [ , [alias.]$num_col_fich[.élément] ... ] FROM ... )

Nécessaire pour transformer les données lors du chargement

Spécifie un ensemble explicite de champs/colonnes (séparés par des virgules) à charger à partir des fichiers de données préparés. Les champs/colonnes sont sélectionnés parmi les fichiers à l’aide d’une requête SQL standard (c’est-à-dire SELECT list), où :

alias

Spécifie un alias facultatif.

num_col_fich

Indique le numéro de position du champ/colonne (dans le fichier) qui contient les données à charger (1 pour le premier champ, 2 pour le second champ, etc.).

élément

Spécifie le chemin et le nom de l’élément d’une valeur répétitive dans le fichier de données (s’applique uniquement aux fichiers de données semi-structurées).

SELECT list définit un ensemble numéroté de champs/colonnes dans les fichiers de données à partir desquels vous chargez les données. La liste doit correspondre à la séquence des colonnes de la table cible. Vous pouvez utiliser le paramètre facultatif ( nom_col [ , nom_col ... ] ) pour mapper la liste à des colonnes spécifiques de la table cible.

Notez que l’ordre réel des champs/colonnes dans les fichiers de données peut être différent de celui des colonnes dans la table cible. Il est surtout important que SELECT list mappe les champs/colonnes des fichiers de données aux colonnes correspondantes de la table.

Note

L’instruction SELECT utilisée pour les transformations ne prend pas toutes les fonctions en charge. Pour une liste complète des fonctions prises en charge et plus de détails sur les transformations de chargement de données, y compris des exemples, voir les notes sur l’utilisation dans la section Transformation des données pendant un chargement.

De plus, la transformation du chargement des données accepte uniquement la sélection des données des zones de préparation utilisateur et des zones de préparation nommées (internes ou externes).

( nom_col [ , nom_col ... ] )

Spécifie de manière facultative une liste explicite de colonnes de la table (séparées par des virgules) dans lesquelles vous voulez insérer des données :

  • La première colonne consomme les valeurs produites à partir du premier champ/première colonne extraits des fichiers chargés.

  • La deuxième colonne consomme les valeurs produites à partir du deuxième champ/colonne extrait(e) des fichiers chargés.

  • Et ainsi de suite, dans l’ordre spécifié.

Les colonnes ne peuvent pas être répétées dans cette liste. Toutes les colonnes exclues de cette liste de colonnes sont remplies par leur valeur par défaut (NULL, si non spécifié). Cependant, les colonnes exclues ne peuvent pas avoir une séquence comme valeur par défaut.

Paramètres facultatifs

FILES = ( 'nom_fichier' [ , 'nom_fichier' ... ] )

Spécifie une liste d’un ou plusieurs noms de fichiers (séparés par des virgules) à charger. Les fichiers doivent déjà avoir été préparés dans l’emplacement interne de Snowflake ou dans l’emplacement externe spécifié dans la commande.

Le nombre maximum de noms de fichiers pouvant être spécifiés est de 1 000.

Note

Pour les zones de préparation externes seulement (c.-à-d. Amazon S3, Google Cloud Storage ou Microsoft Azure), le chemin du fichier est défini en concaténant l’URL dans la définition de la zone de préparation et la liste des noms de fichiers résolus.

Cependant, Snowflake n’insère pas implicitement un séparateur entre le chemin et le nom du fichier. Vous devez explicitement inclure un séparateur (/) soit à la fin de l’URL dans la définition de la zone de préparation, soit au début de chaque nom de fichier spécifié dans ce paramètre.

PATTERN = 'motif_regex'

Chaîne de motifs d’expressions régulières, délimitée par des guillemets simples, spécifiant les noms de fichiers et/ou les chemins à associer.

Astuce

Pour de meilleures performances, évitez d’appliquer des motifs qui filtrent un grand nombre de fichiers.

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

Spécifie le format des fichiers de données à charger :

FORMAT_NAME = 'nom_format_fichier'

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

TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]

Spécifie le type de fichiers à charger dans 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 ce chapitre).

Note

FORMAT_NAME et TYPE s’excluent mutuellement ; spécifier les deux dans la même commande COPY peut entraîner un comportement inattendu.

COPY_OPTIONS = ( ... )

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

VALIDATION_MODE = RETURN_n_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS

Chaîne (constante) qui demande à la commande COPY de valider les fichiers de données au lieu de les charger dans la table spécifiée ; autrement dit, la commande COPY vérifie si les fichiers contiennent des erreurs, mais ne les charge pas. La commande valide les données à charger et renvoie les résultats en fonction de l’option de validation spécifiée :

Valeurs prises en charge

Remarques

RETURN_n_ROWS (par exemple RETURN_10_ROWS)

Valide le nombre de lignes spécifié, si aucune erreur n’est rencontrée ; sinon, échoue à la première erreur rencontrée dans les lignes.

RETURN_ERRORS

Renvoie toutes les erreurs (analyse, conversion, etc.) dans tous les fichiers spécifiés dans l’instruction COPY.

RETURN_ALL_ERRORS

Renvoie toutes les erreurs dans tous les fichiers spécifiés dans l’instruction COPY, y compris les fichiers contenant des erreurs qui ont été partiellement chargées lors d’un chargement précédent parce que l’option de copie ON_ERROR était définie sur CONTINUE lors du chargement.

Note

  • VALIDATION_MODE ne prend pas en charge les instructions COPY qui transforment les données pendant un chargement. Si le paramètre est spécifié, l’instruction COPY renvoie une erreur.

  • Utilisez la fonction de table VALIDATE pour visualiser toutes les erreurs rencontrées lors d’un chargement précédent. Notez que cette fonction ne prend pas non plus en charge les instructions COPY qui transforment les données pendant un chargement.

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 l’algorithme de compression actuel pour les fichiers de données à charger. Snowflake utilise cette option pour détecter comment les fichiers de données déjà compressés ont été compressés afin que les données compressées dans les fichiers puissent être extraites en vue d’un chargement.

Valeurs prises en charge

Remarques

AUTO

Algorithme de compression détecté automatiquement, sauf pour les fichiers compressés par Brotli, qui ne peuvent actuellement pas être détectés automatiquement. Si vous chargez des fichiers compressés via Brotli, utilisez explicitement BROTLI au lieu de AUTO.

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

Fichiers compressés Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Fichiers bruts compressés Deflate (sans en-tête, RFC1951).

NONE

Les fichiers de données à charger n’ont pas été compressés.

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.

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. Notez que « nouvelle ligne » fait sens, de sorte que \r\n sera compris comme une nouvelle ligne pour les fichiers sur une plate-forme Windows.

FIELD_DELIMITER = 'caractère' | NONE

Un ou plusieurs caractères à un octet ou à plusieurs octets qui séparent les champs dans un fichier d’entrée.

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 (,)

SKIP_HEADER = entier

Nombre de lignes au début du fichier à ignorer.

Notez que SKIP_HEADER n’utilise pas les valeurs RECORD_DELIMITER ou FIELD_DELIMITER pour déterminer la nature d’une ligne d’en-tête. Au lieu de cela, il ignore simplement le nombre spécifié de lignes délimitées par CRLF (retour chariot, saut de ligne) dans le fichier. RECORD_DELIMITER et FIELD_DELIMITER sont ensuite utilisés pour déterminer les lignes de données à charger.

Par défaut : 0

DATE_FORMAT = 'chaîne' | AUTO

Chaîne qui définit le format des valeurs de date dans les fichiers de données à charger. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre de session DATE_INPUT_FORMAT est utilisée.

Par défaut : AUTO

TIME_FORMAT = 'chaîne' | AUTO

Chaîne qui définit le format des valeurs de temps dans les fichiers de données à charger. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre de session TIME_INPUT_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 à charger. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre de session TIMESTAMP_INPUT_FORMAT est utilisée.

Par défaut : AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

Chaîne (constante) qui définit le format d’encodage pour l’entrée ou la sortie binaire. Cette option ne s’applique qu’au chargement des données dans les colonnes binaires d’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écifie le caractère d’échappement pour les champs délimités. Spécifiez le caractère utilisé pour délimiter les champs en définissant FIELD_OPTIONALLY_ENCLOSED_BY.

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.

Par défaut

barre oblique inverse (\\)

TRIM_SPACE = TRUE | FALSE

Booléen qui spécifie s’il faut supprimer les espaces blancs des champs.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Utilisez cette option pour supprimer les espaces indésirables pendant le chargement des données.

Comme autre exemple, si les espaces d’en-tête ou de fin entourent des guillemets qui délimitent les chaînes, vous pouvez supprimer les espaces environnants en utilisant l’option TRIM_SPACE et le caractère guillemet en utilisant l’option FIELD_OPTIONALLY_ENCLOSED_BY. Notez que tous les espaces entre les guillemets sont préservés.

Par exemple, en supposant que le délimiteur de champ soit | et FIELD_OPTIONALLY_ENCLOSED_BY = '"' :

|"Hello world"|
|" Hello world "|
| "Hello world" |

devient :

+---------------+
| C1            |
|----+----------|
| Hello world   |
|  Hello world  |
| Hello world   |
+---------------+

Par défaut : FALSE

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 les conversions entrante et sortante de SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\ [par défaut])

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE

Booléen qui spécifie s’il faut générer une erreur d’analyse si le nombre de colonnes délimitées (c’est-à-dire de champs) dans un fichier de données d’entrée ne correspond pas au nombre de colonnes de la table correspondante.

Si ce paramètre est réglé sur FALSE, aucune erreur n’est générée et le chargement continue. Si le fichier est chargé correctement :

  • Si le fichier d’entrée contient des enregistrements contenant plus de champs que de colonnes dans la table, les champs correspondants sont chargés par ordre d’occurrence dans le fichier et les autres champs ne sont pas chargés.

  • Si le fichier d’entrée contient des enregistrements avec moins de champs que de colonnes dans la table, les colonnes qui ne correspondent pas dans la table sont chargées avec des valeurs NULL.

Cette option suppose que tous les enregistrements du fichier d’entrée ont la même longueur (c’est-à-dire qu’un fichier contenant des enregistrements de longueur variable renvoie une erreur quelle que soit la valeur spécifiée pour cette option).

Par défaut : TRUE

Note

Lors de la transformation des données pendant le chargement (c’est-à-dire, en utilisant une requête comme source pour la commande COPY), cette option est ignorée. Il n’est pas nécessaire que vos fichiers de données aient le même nombre et le même ordre de colonnes que votre table cible.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Booléen qui spécifie s’il faut remplacer les caractères UTF-8 non valides par le caractère de remplacement Unicode ().

S’il est défini sur TRUE, Snowflake remplace les caractères UTF-8 non valides par le caractère de remplacement Unicode.

S’il est défini sur FALSE, l’opération de chargement génère une erreur lorsqu’un codage de caractères UTF-8 non valide est détecté.

Par défaut : FALSE

VALIDATE_UTF8 = TRUE | FALSE

Booléen qui spécifie s’il faut valider l’encodage des caractères UTF-8 dans les données de colonne de chaîne.

S’il est réglé sur TRUE, Snowflake valide l’encodage des caractères UTF-8 dans les données de colonne de chaîne. Lorsqu’un encodage de caractères UTF-8 non valide est détecté, la commande COPY produit une erreur.

Par défaut : TRUE

Important

Cette option n’est fournie que pour assurer une rétrocompatibilité avec les versions antérieures de Snowflake. Nous vous recommandons de conserver cette option à moins que l’assistance de Snowflake ne vous demande de la désactiver.

EMPTY_FIELD_AS_NULL = TRUE | FALSE

Booléen qui spécifie s’il faut insérer SQL NULL pour les champs vides dans un fichier d’entrée, qui sont représentés par deux délimiteurs successifs (par ex., ,,).

Si l’option est définie sur FALSE, Snowflake essaie de placer un champ vide dans le type de colonne correspondant. Une chaîne vide est insérée dans les colonnes de type STRING. Pour les autres types de colonne, la commande COPY produit une erreur.

Par défaut : TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booléen qui spécifie s’il faut ignorer le BOM (marque d’ordre d’octet), s’il est présent dans un fichier de données. Une marque BOM est un code de caractère placé au début d’un fichier de données qui définit l’ordre des octets et la forme de l’encodage.

S’il est réglé sur FALSE, Snowflake reconnaît n’importe quel BOM dans les fichiers de données, ce qui pourrait entraîner une erreur BOM ou une fusion dans la première colonne du tableau.

Par défaut : TRUE

ENCODING = 'chaîne'

Chaîne (constante) qui spécifie le jeu de caractères des données sources.

Jeu de caractères

Valeur ENCODING 

Langues acceptées

Remarques

Big5

BIG5

Chinois traditionnel

EUC-JP

EUCJP

Japonais

EUC-KR

EUCKR

Coréen

GB18030

GB18030

Chinois

IBM420

IBM420

Arabe

IBM424

IBM424

Hébreu

ISO-2022-CN

ISO2022CN

Chinois simplifié

ISO-2022-JP

ISO2022JP

Japonais

ISO-2022-KR

ISO2022KR

Coréen

ISO-8859-1

ISO88591

Allemand, anglais, danois, français, italien, norvégien, néerlandais, portugais, suédois

ISO-8859-2

ISO88592

Tchèque, hongrois, polonais, roumain

ISO-8859-5

ISO88595

Russe

ISO-8859-6

ISO88596

Arabe

ISO-8859-7

ISO88597

Grec

ISO-8859-8

ISO88598

Hébreu

ISO-8859-9

ISO88599

Turc

KOI8-R

KOI8R

Russe

Shift_JIS

SHIFTJIS

Japonais

UTF-8

UTF8

Toutes les langues

Pour charger des données à partir de fichiers délimités (CSV, TSV, etc.), UTF-8 est la valeur par défaut. . . Pour charger des données à partir de tous les autres formats de fichier pris en charge (JSON, Avro, etc.), ainsi que pour décharger des données, UTF-8 est le seul jeu de caractères pris en charge.

UTF-16

UTF16

Toutes les langues

UTF-16BE

UTF16BE

Toutes les langues

UTF-16LE

UTF16LE

Toutes les langues

UTF-32

UTF32

Toutes les langues

UTF-32BE

UTF32BE

Toutes les langues

UTF-32LE

UTF32LE

Toutes les langues

windows-1250

WINDOWS1250

Tchèque, hongrois, polonais, roumain

windows-1251

WINDOWS1251

Russe

windows-1252

WINDOWS1252

Allemand, anglais, danois, français, italien, norvégien, néerlandais, portugais, suédois

windows-1253

WINDOWS1253

Grec

windows-1254

WINDOWS1254

Turc

windows-1255

WINDOWS1255

Hébreu

windows-1256

WINDOWS1256

Arabe

Par défaut : UTF8

Note

Snowflake stocke toutes les données en interne dans le jeu de caractères UTF-8. Les données sont converties en UTF-8 avant d’être chargées dans Snowflake. Si l’option de format de fichier VALIDATE_UTF8 est TRUE, Snowflake valide l’encodage de caractères UTF-8 dans les données de colonnes de chaînes après sa conversion à partir de son encodage de caractères original.

TYPE = JSON

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

Chaîne (constante) qui spécifie l’algorithme de compression actuel pour les fichiers de données à charger. Snowflake utilise cette option pour détecter comment les fichiers de données déjà compressés ont été compressés afin que les données compressées dans les fichiers puissent être extraites en vue d’un chargement.

Valeurs prises en charge

Remarques

AUTO

Algorithme de compression détecté automatiquement, sauf pour les fichiers compressés par Brotli, qui ne peuvent actuellement pas être détectés automatiquement. Si vous chargez des fichiers compressés via Brotli, utilisez explicitement BROTLI au lieu de AUTO.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Fichiers compressés Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Fichiers bruts compressés Deflate (sans en-tête, RFC1951).

NONE

Indique que les fichiers de chargement des données n’ont pas été compressés.

Par défaut : AUTO

DATE_FORMAT = 'chaîne' | AUTO

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Définit le format des valeurs de chaînes de date dans les fichiers de données. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre DATE_INPUT_FORMAT est utilisée.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : AUTO

TIME_FORMAT = 'chaîne' | AUTO

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Définit le format des valeurs de chaînes d’heure dans les fichiers de données. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre TIME_INPUT_FORMAT est utilisée.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : AUTO

TIMESTAMP_FORMAT = chaîne' | AUTO

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Définit le format des valeurs de chaînes d’horodatage dans les fichiers de données. Si une valeur n’est pas spécifiée ou est AUTO, la valeur du paramètre TIMESTAMP_INPUT_FORMAT est utilisée.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Définit le format d’encodage des valeurs de chaînes binaires dans les fichiers de données. L’option peut être utilisée pour charger des données à partir de colonnes binaires dans une table.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : HEX

TRIM_SPACE = TRUE | FALSE

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Booléen qui spécifie s’il faut supprimer les espaces blancs de début et de fin des chaînes.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Définissez cette option sur TRUE pour supprimer les espaces indésirables pendant le chargement des données.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : FALSE

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

S’applique uniquement lors du chargement de données JSON dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Chaîne utilisée pour effectuer des conversions vers et depuis SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\)

ENABLE_OCTAL = TRUE | FALSE

Booléen qui permet d’analyser les nombres octaux.

Par défaut : FALSE

ALLOW_DUPLICATE = TRUE | FALSE

Booléen qui permet de dupliquer les noms de champs d’objets (seul le dernier sera conservé).

Par défaut : FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE

Booléen qui demande à l’analyseur JSON de supprimer les crochets extérieurs [ ].

Par défaut : FALSE

STRIP_NULL_VALUES = TRUE | FALSE

Booléen qui demande à l’analyseur JSON de supprimer les champs d’objets ou les éléments de tableau contenant des valeurs null. Par exemple, lorsque défini sur TRUE :

Avant

Après

[null]

[]

[null,null,3]

[,,3]

{"a":null,"b":null,"c":123}

{"c":123}

{"a":[1,null,2],"b":{"x":null,"y":88}}

{"a":[1,,2],"b":{"y":88}}

Par défaut : FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE

Booléen qui spécifie si les erreurs d’encodage UTF-8 produisent des conditions d’erreur. Si ce paramètre est réglé sur TRUE, toute séquence UTF-8 non valide est remplacée discrètement par un caractère Unicode U+FFFD (c.-à-d. un « caractère de remplacement »).

Par défaut : FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booléen qui spécifie s’il faut sauter n’importe quel BOM (marque d’ordre d’octet) présent dans un fichier d’entrée. Une marque BOM est un code de caractère placé au début d’un fichier de données qui définit l’ordre des octets et la forme de l’encodage.

S’il est réglé sur FALSE, Snowflake reconnaît n’importe quel BOM dans les fichiers de données, ce qui pourrait entraîner une erreur BOM ou une fusion dans la première colonne du tableau.

Par défaut : TRUE

TYPE = AVRO

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

Chaîne (constante) qui spécifie l’algorithme de compression actuel pour les fichiers de données à charger. Snowflake utilise cette option pour détecter comment les fichiers de données déjà compressés ont été compressés afin que les données compressées dans les fichiers puissent être extraites en vue d’un chargement.

Valeurs prises en charge

Remarques

AUTO

Algorithme de compression détecté automatiquement, sauf pour les fichiers compressés par Brotli, qui ne peuvent actuellement pas être détectés automatiquement. Si vous chargez des fichiers compressés via Brotli, utilisez explicitement BROTLI au lieu de AUTO.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Fichiers compressés Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Fichiers bruts compressés Deflate (sans en-tête, RFC1951).

NONE

Les fichiers de données à charger n’ont pas été compressés.

Par défaut : AUTO

TRIM_SPACE = TRUE | FALSE

S’applique uniquement lors du chargement de données Avro dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Booléen qui spécifie s’il faut supprimer les espaces blancs de début et de fin des chaînes.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Définissez cette option sur TRUE pour supprimer les espaces indésirables pendant le chargement des données.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : FALSE

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

S’applique uniquement lors du chargement de données Avro dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Chaîne utilisée pour effectuer des conversions vers et depuis SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\)

TYPE = ORC

TRIM_SPACE = TRUE | FALSE

S’applique uniquement lors du chargement de données ORC dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Booléen qui spécifie s’il faut supprimer les espaces blancs de début et de fin des chaînes.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Définissez cette option sur TRUE pour supprimer les espaces indésirables pendant le chargement des données.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : FALSE

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

S’applique uniquement lors du chargement de données ORC dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Chaîne utilisée pour effectuer des conversions vers et depuis SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\)

TYPE = PARQUET

COMPRESSION = AUTO | SNAPPY | NONE

Chaîne (constante) qui spécifie l’algorithme de compression actuel pour les fichiers de données à charger. Snowflake utilise cette option pour détecter comment les fichiers de données déjà compressés ont été compressés afin que les données compressées dans les fichiers puissent être extraites en vue d’un chargement.

Valeurs prises en charge

Remarques

AUTO

Algorithme de compression détecté automatiquement. Prend en charge les algorithmes de compression suivants : Brotli, gzip, Lempel–Ziv–Oberhumer (LZO), LZ4, Snappy ou Zstandard v0.8 (et versions ultérieures).

SNAPPY

NONE

Les fichiers de données à charger n’ont pas été compressés.

BINARY_AS_TEXT = TRUE | FALSE

Booléen qui spécifie s’il faut interpréter les colonnes sans type de données logiques défini comme du texte UTF-8. Lorsqu’il est réglé sur FALSE, Snowflake interprète ces colonnes comme des données binaires.

Par défaut : TRUE

TRIM_SPACE = TRUE | FALSE

S’applique uniquement lors du chargement de données Parquet dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Booléen qui spécifie s’il faut supprimer les espaces blancs de début et de fin des chaînes.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Définissez cette option sur TRUE pour supprimer les espaces indésirables pendant le chargement des données.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : FALSE

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

S’applique uniquement lors du chargement de données Parquet dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Chaîne utilisée pour effectuer des conversions vers et depuis SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\)

TYPE = XML

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

Chaîne (constante) qui spécifie l’algorithme de compression actuel pour les fichiers de données à charger. Snowflake utilise cette option pour détecter comment les fichiers de données déjà compressés ont été compressés afin que les données compressées dans les fichiers puissent être extraites en vue d’un chargement.

Valeurs prises en charge

Remarques

AUTO

Algorithme de compression détecté automatiquement, sauf pour les fichiers compressés par Brotli, qui ne peuvent actuellement pas être détectés automatiquement. Si vous chargez des fichiers compressés via Brotli, utilisez explicitement BROTLI au lieu de AUTO.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

Fichiers compressés Deflate (avec en-tête zlib, RFC1950).

RAW_DEFLATE

Fichiers bruts compressés Deflate (sans en-tête, RFC1951).

NONE

Les fichiers de données à charger n’ont pas été compressés.

Par défaut : AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE

Booléen qui spécifie si les erreurs d’encodage UTF-8 produisent des conditions d’erreur. Si ce paramètre est réglé sur TRUE, toute séquence UTF-8 non valide est remplacée discrètement par un caractère Unicode U+FFFD (c.-à-d. un « caractère de remplacement »).

Par défaut : FALSE

PRESERVE_SPACE = TRUE | FALSE

Booléen qui spécifie si l’analyseur XML préserve les espaces d’en-tête et de fin dans le contenu des éléments.

Par défaut : FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE

Booléen qui spécifie si l’analyseur XML supprime l’élément externe XML, exposant les éléments de 2e niveau comme des documents séparés.

Par défaut : FALSE

DISABLE_SNOWFLAKE_DATA = TRUE | FALSE

Booléen qui spécifie si l’analyseur XML désactive la reconnaissance des balises de données semi-structurées Snowflake.

Par défaut : FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE

Booléen qui spécifie si l’analyseur XML désactive la conversion automatique des valeurs numériques et booléennes du texte en représentation native.

Par défaut : FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Booléen qui spécifie s’il faut sauter n’importe quel BOM (marque d’ordre d’octet) présent dans un fichier d’entrée. Une marque BOM est un code de caractère placé au début d’un fichier de données qui définit l’ordre des octets et la forme de l’encodage.

S’il est réglé sur FALSE, Snowflake reconnaît n’importe quel BOM dans les fichiers de données, ce qui pourrait entraîner une erreur BOM ou une fusion dans la première colonne du tableau.

Par défaut : TRUE

TRIM_SPACE = TRUE | FALSE

S’applique uniquement lors du chargement de données XML dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Booléen qui spécifie s’il faut supprimer les espaces blancs de début et de fin des chaînes.

Par exemple, si votre logiciel de base de données externe contient des champs entre guillemets, mais insère un espace d’en-tête, Snowflake lit l’espace d’en-tête plutôt que le caractère guillemet comme début du champ (c’est-à-dire que les guillemets sont interprétés comme faisant partie de la chaîne des données du champ). Définissez cette option sur TRUE pour supprimer les espaces indésirables pendant le chargement des données.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : FALSE

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

S’applique uniquement lors du chargement de données XML dans des colonnes distinctes (c’est-à-dire en utilisant l’option de copie MATCH_BY_COLUMN_NAME ou une transformation COPY). Chaîne utilisée pour effectuer des conversions vers et depuis SQL NULL. Snowflake remplace ces chaînes de la source de chargement des données par SQL NULL. Pour spécifier plus d’une chaîne, mettez la liste des chaînes entre parenthèses et utilisez des virgules pour séparer chaque valeur.

Par exemple :

NULL_IF = ('\\N', 'NULL', 'NUL', '')

Notez que cette option peut inclure des chaînes vides.

Cette option de format de fichier est actuellement une fonction d’aperçu.

Par défaut : \\N (comme NULL, ce qui suppose que la valeur ESCAPE_UNENCLOSED_FIELD est \\)

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

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_nb | SKIP_FILE_nb% | ABORT_STATEMENT

Chaîne (constante) qui spécifie l’action à effectuer lorsqu’une erreur se produit lors du chargement de données à partir d’un fichier :

Valeurs prises en charge

Remarques

CONTINUE

Continuez à charger le fichier. L’instruction COPY renvoie un message d’erreur pour un maximum d’une erreur rencontrée par fichier de données. Notez que la différence entre les valeurs des colonnes ROWS_PARSED et ROWS_LOADED représente le nombre de lignes qui incluent les erreurs détectées. Cependant, chacune de ces lignes peut contenir plusieurs erreurs. Pour afficher toutes les erreurs dans les fichiers de données, utilisez le paramètre VALIDATION_MODE ou interrogez la fonction VALIDATE.

SKIP_FILE

Ignorez le fichier s’il y a des erreurs rencontrées dans le fichier.

SKIP_FILE_nb (par exemple SKIP_FILE_10)

Ignorez le fichier lorsque le nombre d’erreurs dans le fichier est égal ou supérieur au nombre spécifié.

SKIP_FILE_nb% (par exemple SKIP_FILE_10%)

Ignorez le fichier lorsque le pourcentage d’erreurs dans le fichier dépasse le pourcentage spécifié.

ABORT_STATEMENT

Annulez l’instruction COPY en cas d’erreur.

Par défaut :

Chargement en lot à l’aide de COPY

ABORT_STATEMENT

Snowpipe

SKIP_FILE

SIZE_LIMIT = nb

Nombre (> 0) qui spécifie la taille maximale (en octets) des données à charger pour une instruction COPY donnée. Lorsque le seuil est dépassé, l’opération COPY interrompt le chargement des fichiers. Cette option est couramment utilisée pour charger un groupe commun de fichiers en utilisant plusieurs instructions COPY. Pour chaque instruction, la charge de données continue jusqu’à ce que le SIZE_LIMIT spécifié soit dépassé, avant de passer à l’instruction suivante.

Par exemple, supposons que des fichiers dans un chemin d’accès de zone de préparation présentent chacun une taille de 10 MB. Si plusieurs instructions COPY établissent SIZE_LIMIT à 25000000 (25 MB), chacune chargerait 3 fichiers. En d’autres termes, chaque opération COPY serait interrompue après le dépassement du seuil SIZE_LIMIT.

Notez qu’au moins un fichier est chargé, quelle que soit la valeur spécifiée pour SIZE_LIMIT:code: à moins qu’il n’y ait aucun fichier à charger.

Valeur par défaut : null (aucune limite de taille)

PURGE = TRUE | FALSE

Booléen qui spécifie s’il faut supprimer automatiquement les fichiers de données de la zone de préparation une fois que les données ont été chargées avec succès.

Si cette option est définie sur TRUE, nous faisons de notre mieux pour supprimer les fichiers de données chargés avec succès. Si l’opération de purge échoue pour une raison quelconque, aucune erreur n’est renvoyée actuellement. Nous vous recommandons de répertorier périodiquement les fichiers mis en zone de préparation (à l’aide de LIST) et de supprimer manuellement les fichiers correctement chargés, le cas échéant.

Par défaut : FALSE

RETURN_FAILED_ONLY = TRUE | FALSE

Booléen qui spécifie s’il faut renvoyer uniquement les fichiers qui n’ont pas réussi à se charger dans le résultat de l’instruction.

Par défaut : FALSE

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE

Chaîne qui spécifie si elle doit charger des données semi-structurées dans des colonnes de la table cible qui correspondent aux colonnes correspondantes représentées dans les données.

Pour qu’une colonne corresponde, les critères suivants doivent être remplis :

  • La colonne représentée dans les données doit avoir exactement le même nom que la colonne de la table. L’option de copie prend en charge la casse pour les noms de colonne. L’ordre des colonnes n’a pas d’importance.

  • La colonne de la table doit avoir un type de données compatible avec les valeurs de la colonne représentée dans les données. Par exemple, la chaîne, le nombre et les valeurs booléennes peuvent tous être chargés dans une colonne de variantes.

Les options suivantes sont prises en charge :

CASE_SENSITIVE | CASE_INSENSITIVE

Chargez des données semi-structurées dans des colonnes de la table cible qui correspondent aux colonnes correspondantes représentées dans les données. Les noms de colonne sont sensibles à la casse (CASE_SENSITIVE) ou ne sont pas sensibles à la casse (CASE_INSENSITIVE).

L’opération COPY vérifie qu’au moins une colonne de la table cible correspond à une colonne représentée dans les fichiers de données. Si une correspondance est trouvée, les valeurs des fichiers de données sont chargées dans la ou les colonnes. Si aucune correspondance n’est trouvée, un ensemble de valeurs NULL pour chaque enregistrement des fichiers est chargé dans la table.

Note

  • Si des colonnes supplémentaires non correspondantes sont présentes dans les fichiers de données, les valeurs de ces colonnes ne sont pas chargées.

  • Si des colonnes non correspondantes supplémentaires sont présentes dans la table cible, l’opération COPY insère des valeurs NULL dans ces colonnes. Ces colonnes doivent prendre en charge les valeurs NULL.

  • L’instruction COPY ne permet pas de spécifier une requête pour transformer davantage les données pendant le chargement (c’est-à-dire transformation COPY).

NONE

L’opération COPY charge les données semi-structurées dans une colonne variante ou, si une requête est incluse dans l’instruction COPY, transforme les données.

Par défaut

NONE

Note

Les limitations suivantes s’appliquent actuellement :

  • MATCH_BY_COLUMN_NAME ne peut pas être utilisé avec le paramètre VALIDATION_MODE dans une instruction COPY pour valider les données de zone de préparation plutôt que de les charger dans la table cible.

  • Données Parquet uniquement. Lorsque MATCH_BY_COLUMN_NAME est défini sur CASE_SENSITIVE ou CASE_INSENSITIVE, une valeur de colonne vide (par exemple "col1": "") génère une erreur.

ENFORCE_LENGTH = TRUE | FALSE

Syntaxe alternative pour TRUNCATECOLUMNS avec logique inverse (pour assurer une compatibilité avec les autres systèmes)

Booléen qui spécifie s’il faut tronquer les chaînes de texte qui dépassent la longueur de colonne cible :

  • Si TRUE, l’instruction COPY produit une erreur si une chaîne chargée dépasse la longueur de la colonne cible.

  • Si FALSE, les chaînes sont automatiquement tronquées suivant la longueur de colonne cible.

Actuellement, cette option de copie prend uniquement en charge les données CSV.

Par défaut : TRUE

Note

  • Si la longueur de la colonne de la chaîne de caractères cible est réglée au maximum (par exemple, VARCHAR (16777216)), une chaîne entrante ne peut pas dépasser cette longueur ; sinon, la commande COPY produit une erreur.

  • Ce paramètre est fonctionnellement équivalent à TRUNCATECOLUMNS, mais a le comportement inverse. Il est fourni pour assurer une compatibilité avec d’autres bases de données. Il n’est nécessaire d’inclure qu’un seul de ces deux paramètres dans une instruction COPY pour produire le résultat souhaité.

TRUNCATECOLUMNS = TRUE | FALSE

Syntaxe alternative pour ENFORCE_LENGTH avec logique inverse (pour assurer une compatibilité avec les autres systèmes)

Booléen qui spécifie s’il faut tronquer les chaînes de texte qui dépassent la longueur de colonne cible :

  • Si TRUE, les chaînes sont automatiquement tronquées suivant la longueur de colonne cible.

  • Si FALSE, l’instruction COPY produit une erreur si une chaîne chargée dépasse la longueur de la colonne cible.

Actuellement, cette option de copie prend uniquement en charge les données CSV.

Par défaut : FALSE

Note

  • Si la longueur de la colonne de la chaîne de caractères cible est réglée au maximum (par exemple, VARCHAR (16777216)), une chaîne entrante ne peut pas dépasser cette longueur ; sinon, la commande COPY produit une erreur.

  • Ce paramètre est fonctionnellement équivalent à ENFORCE_LENGTH, mais a le comportement inverse. Il est fourni pour assurer une compatibilité avec d’autres bases de données. Il n’est nécessaire d’inclure qu’un seul de ces deux paramètres dans une instruction COPY pour produire le résultat souhaité.

FORCE = TRUE | FALSE

Booléen qui demande de charger tous les fichiers, qu’ils aient été chargés précédemment ou non et qu’ils n’aient pas changé depuis leur chargement. Notez que cette option recharge les fichiers, dupliquant potentiellement les données dans une table.

Par défaut : FALSE

LOAD_UNCERTAIN_FILES = TRUE | FALSE

Booléen qui spécifie de charger les fichiers pour lesquels le statut de chargement est inconnu. La commande COPY ignore ces fichiers par défaut.

Le statut de chargement est inconnu si toutes les conditions suivantes sont réunies :

  • La date LAST_MODIFIED du fichier (c.-à-d. la date à laquelle le fichier a été mis en zone de préparation) remonte à plus de 64 jours.

  • L’ensemble initial de données a été chargé dans la table il y a plus de 64 jours.

  • Si le fichier a déjà été chargé avec succès dans la table, cet événement s’est produit plus de 64 jours auparavant.

Pour forcer la commande COPY à charger tous les fichiers, que le statut de chargement soit connu ou non, utilisez plutôt l’option FORCE.

Pour plus d’informations sur les statuts de chargement incertains, voir Chargement d’anciens fichiers.

Par défaut : FALSE

Notes sur l’utilisation

  • En cas de chargement dans une table à partir de sa propre zone de préparation de table, la clause FROM n’est pas nécessaire et peut être omise.

  • Lors de la transformation des données pendant le chargement (c’est-à-dire, en utilisant une requête comme source pour la commande COPY) :

    • La sélection de données à partir de fichiers n’est prise en charge que par les zones de préparation nommées (internes ou externes) et les zones de préparation d’utilisateur. Cela n’est pas pris en charge par les zones de préparation de la table.

    • Les types de fichiers CSV et semi-structurés sont pris en charge ; cependant, même lors du chargement de données semi-structurées (par ex. JSON), vous devez définir CSV comme type de format de fichier (valeur par défaut). Vous pouvez utiliser le format de fichier correspondant (par ex. JSON), mais toute erreur dans la transformation arrêtera l’opération COPY, même si vous définissez l’option ON_ERROR pour continuer ou ignorer le fichier.

      De plus, définissez l’option de format de fichier FIELD_DELIMITER = NONE.

    • Pour transformer des données JSON pendant une opération de chargement, vous devez structurer les fichiers de données au format standard NDJSON (« Newline Delimited JSON ») ; sinon, vous risquez de rencontrer l’erreur suivante :

      Error parsing JSON: more than one document in the input

    • Le mot clé DISTINCT dans les instructions SELECT n’est pas totalement pris en charge. La spécification du mot clé peut entraîner un comportement incohérent ou inattendu de l’option de copie ON_ERROR.

  • Chargement à partir de Google Cloud Storage uniquement : la liste des objets renvoyés pour une zone de préparation externe peut inclure un ou plusieurs « blobs de répertoire » ; essentiellement, les chemins qui se terminent par une barre oblique (/), par exemple :

    LIST @my_gcs_stage;
    
    +---------------------------------------+------+----------------------------------+-------------------------------+
    | name                                  | size | md5                              | last_modified                 |
    |---------------------------------------+------+----------------------------------+-------------------------------|
    | my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Sep 2019 16:57:43 GMT |
    | my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Sep 2019 18:13:07 GMT |
    +---------------------------------------+------+----------------------------------+-------------------------------+
    

    Ces blobs sont répertoriés lorsque des répertoires sont créés dans la console Google Cloud Platform plutôt que d’utiliser un autre outil fourni par Google.

    Les instructions COPY qui font référence à une zone de préparation peuvent échouer lorsque la liste d’objets inclut des blobs de répertoire. Pour éviter les erreurs, nous vous recommandons d’utiliser la correspondance de motifs de fichier pour identifier les fichiers à inclure (c’est-à-dire la clause PATTERN) lorsque la liste de fichiers d’une zone de préparation inclut des blobs de répertoire. Pour un exemple, voir Chargement à l’aide de critères spéciaux (dans ce chapitre). Vous pouvez également définir ON_ERROR = SKIP_FILE dans l’instruction COPY.

  • Si vous faites référence à un format de fichier dans l’espace de noms actuel (la base de données et le schéma actifs dans la session utilisateur en cours), vous pouvez omettre les guillemets simples autour de l’identificateur de format.

  • STORAGE_INTEGRATION, CREDENTIALS et ENCRYPTION ne s’appliquent que si vous chargez des données directement à partir d’un emplacement de stockage privé/protégé :

    • Si vous chargez depuis un compartiment public, un accès sécurisé n’est pas requis.

    • Si vous chargez des données à partir d’une zone de préparation externe nommée, la zone de préparation fournit toutes les informations d’identification requises pour accéder au compartiment.

  • Si vous rencontrez des erreurs lors de l’exécution de la commande COPY, une fois la commande terminée, vous pouvez valider les fichiers qui ont produit les erreurs en utilisant la fonction de table VALIDATE.

    Note

    La fonction VALIDATE ne renvoie que les commandes COPY utilisées pour effectuer le chargement standard des données ; elle ne prend pas en charge les commandes COPY qui effectuent des transformations pendant le chargement des données (par exemple, charger un sous-ensemble de colonnes de données ou réorganiser des colonnes de données).

  • À moins d’indiquer explicitement FORCE = TRUE comme l’une des options de copie, la commande ignore les fichiers de données préparés qui ont déjà été chargés dans la table. Pour recharger les données, vous devez soit spécifier FORCE = TRUE, soit modifier le fichier et le préparer à nouveau, ce qui génère une nouvelle somme de contrôle.

  • La commande COPY ne valide pas les conversions de type de données pour les fichiers Parquet.

Sortie

La commande renvoie les colonnes suivantes :

Nom de la colonne

Type de données

Description

FILE

TEXT

Nom du fichier source et chemin d’accès relatif au fichier

STATUS

TEXT

Statut : chargé, échec du chargement ou partiellement chargé.

ROWS_PARSED

NUMBER

Nombre de lignes analysées à partir du fichier source

ROWS_LOADED

NUMBER

Nombre de lignes chargées à partir du fichier source

ERROR_LIMIT

NUMBER

Si le nombre d’erreurs atteint cette limite, annulez l’opération

ERRORS_SEEN

NUMBER

Nombre de lignes d’erreur dans le fichier source

FIRST_ERROR

TEXT

Première erreur du fichier source

FIRST_ERROR_LINE

NUMBER

Numéro de ligne de la première erreur

FIRST_ERROR_CHARACTER

NUMBER

Position du premier caractère de l’erreur

FIRST_ERROR_COLUMN_NAME

TEXT

Nom de colonne de la première erreur

Exemples

Pour des exemples de transformations de chargement de données, voir Transformation des données pendant un chargement.

Chargement de fichiers à partir d’une zone de préparation interne

Note

Ces exemples supposent que les fichiers ont été copiés dans la zone de préparation précédente en utilisant la commande PUT.

Charger des fichiers depuis une zone de préparation interne nommée dans une table :

COPY INTO mytable
FROM @my_int_stage;

Charger des fichiers depuis la zone de préparation d’une table dans la table :

COPY INTO mytable
FILE_FORMAT = (TYPE = CSV);

Note

Lors de la copie de données à partir de fichiers dans un emplacement de table, la clause FROM peut être omise, car Snowflake vérifie automatiquement les fichiers dans l’emplacement de la table.

Charger des fichiers depuis la zone de préparation personnelle de l’utilisateur dans une table :

COPY INTO mytable from @~/staged
FILE_FORMAT = (FORMAT_NAME = 'mycsv');

Chargement de fichiers à partir d’une zone de préparation externe nommée

Chargez des fichiers à partir d’une zone de préparation externe nommée que vous avez créée précédemment à l’aide de la commande CREATE STAGE. La zone de préparation externe nommée fait référence à un emplacement externe (c.-à-d. Amazon S3, Google Cloud Storage ou Microsoft Azure) et inclut toutes les informations d’identification et autres informations requises pour accéder à l’emplacement :

COPY INTO mycsvtable
  FROM @my_ext_stage/tutorials/dataloading/contacts1.csv;

Chargement de fichiers directement à partir d’un emplacement externe

L’exemple suivant charge tous les fichiers préfixés par data/files à partir d’un emplacement de stockage (c.-à-d. Amazon S3, Google Cloud Storage ou Microsoft Azure) en utilisant un format de fichier nommé my_csv_format :

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 mytable
  FROM s3://mybucket/data/files
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(MASTER_KEY = 'eSxX0jzYfIamtnBKOEOwq80Au6NbSgPH5r4BDDwOaO8=')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

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

COPY INTO mytable
  FROM s3://mybucket/data/files
  CREDENTIALS=(AWS_KEY_ID='$AWS_ACCESS_KEY_ID' AWS_SECRET_KEY='$AWS_SECRET_ACCESS_KEY')
  ENCRYPTION=(MASTER_KEY = 'eSxX0jzYfIamtnBKOEOwq80Au6NbSgPH5r4BDDwOaO8=')
  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 mytable
  FROM gcs://mybucket/data/files
  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 mytable
  FROM azure://myaccount.blob.core.windows.net/data/files
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPxX0jzYfIamtnJEUTHwq80Au6NbSgPH5r4BDDwOaO8=')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

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

COPY INTO mytable
  FROM azure://myaccount.blob.core.windows.net/mycontainer/data/files
  CREDENTIALS=(AZURE_SAS_TOKEN='?sv=2016-05-31&ss=b&srt=sco&sp=rwdl&se=2018-06-27T10:05:50Z&st=2017-06-27T02:05:50Z&spr=https,http&sig=bgqQwoXwxzuD2GJfagRg7VOS8hzNr3QLT7rhS8OFRLQ%3D')
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPxX0jzYfIamtnJEUTHwq80Au6NbSgPH5r4BDDwOaO8=')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Chargement à l’aide de critères spéciaux

Charger des fichiers à partir de la zone de préparation d’une table dans la table, en utilisant des critères spéciaux pour ne charger que des données à partir de fichiers CSV compressés dans n’importe quel chemin :

COPY INTO mytable
  FILE_FORMAT = (TYPE = 'CSV')
  PATTERN='.*/.*/.*[.]csv[.]gz';

.* est interprété comme « zéro ou plusieurs occurrences d’un caractère quelconque. » Les crochets isolent le caractère point (.) qui précède une extension de fichier.

Charger des fichiers à partir de la zone de préparation d’une table dans la table, en utilisant des critères spéciaux pour ne charger que des fichiers CSV compressés dont les noms incluent la chaîne sales :

COPY INTO mytable
  FILE_FORMAT = (FORMAT_NAME = myformat)
  PATTERN='.*sales.*[.]csv';

Chargement de données JSON dans une colonne VARIANT

L’exemple suivant charge des données JSON dans une table avec une seule colonne de type VARIANT.

Le tableau JSON préparé comprend trois objets séparés par de nouvelles lignes :

[{
    "location": {
      "city": "Lexington",
      "zip": "40503",
      },
      "sq__ft": "1000",
      "sale_date": "4-25-16",
      "price": "75836"
},
{
    "location": {
      "city": "Belmont",
      "zip": "02478",
      },
      "sq__ft": "1103",
      "sale_date": "6-18-16",
      "price": "92567"
}
{
    "location": {
      "city": "Winchester",
      "zip": "01890",
      },
      "sq__ft": "1122",
      "sale_date": "1-31-16",
      "price": "89921"
}]
/* Create a JSON file format that delimits records using the new line character and strips the outer array. */

CREATE OR REPLACE FILE FORMAT json_format
  TYPE = 'JSON'
  FIELD_DELIMITER = NONE
  RECORD_DELIMITER = '\\n'
  STRIP_OUTER_ARRAY = TRUE;

/* Create an internal stage that references the JSON file format. */

CREATE OR REPLACE STAGE mystage
  FILE_FORMAT = json_format;

/* Stage the JSON file. */

PUT file:///tmp/sales.json @mystage AUTO_COMPRESS=TRUE;

/* Create a target table for the JSON data. */

CREATE OR REPLACE TABLE house_sales (src VARIANT);

/* Copy the JSON data into the target table. */

COPY INTO house_sales
   FROM @mystage/sales.json.gz;

SELECT * FROM house_sales;

+---------------------------+
| SRC                       |
|---------------------------|
| {                         |
|   "location": {           |
|     "city": "Lexington",  |
|     "zip": "40503"        |
|   },                      |
|   "price": "75836",       |
|   "sale_date": "4-25-16", |
|   "sq__ft": "1000",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Belmont",    |
|     "zip": "02478"        |
|   },                      |
|   "price": "92567",       |
|   "sale_date": "6-18-16", |
|   "sq__ft": "1103",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Winchester", |
|     "zip": "01890"        |
|   },                      |
|   "price": "89921",       |
|   "sale_date": "1-31-16", |
|   "sq__ft": "1122",       |
|   "type": "Condo"         |
| }                         |
+---------------------------+

Rechargement des fichiers

Ajoutez FORCE = TRUE à une commande COPY pour recharger (dupliquer) des données à partir d’un ensemble de fichiers de données mis en zone de préparation qui n’ont pas été modifiés (c’est-à-dire qu’ils présentent la même somme de contrôle que lorsqu’ils ont été chargés pour la première fois).

Dans cet exemple, la première commande charge les fichiers spécifiés et la seconde commande force les mêmes fichiers à se charger à nouveau (produisant des lignes en double), même si le contenu des fichiers n’a pas changé :

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv')

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv')
    FORCE=TRUE;

Purge des fichiers après le chargement

Chargez les fichiers de la zone de préparation d’une table dans la table et purgez les fichiers après le chargement. Par défaut, COPY ne purge pas les fichiers chargés depuis l’emplacement. Pour purger les fichiers après le chargement :

  • Définissez PURGE=TRUE pour la table pour spécifier que tous les fichiers chargés avec succès dans la table sont purgés après le chargement :

    ALTER TABLE mytable SET STAGE_COPY_OPTIONS = (PURGE = TRUE);
    
    COPY INTO mytable;
    
  • Vous pouvez également remplacer n’importe quelle option de copie directement dans la commande COPY :

    COPY INTO mytable PURGE = TRUE;
    

Validation des fichiers préparés

Validez les fichiers préparés sans chargement :

  • Exécutez la commande COPY en mode validation et voyez toutes les erreurs :

    COPY INTO mytable VALIDATION_MODE = 'RETURN_ERRORS';
    
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    |                                                         ERROR                                                                 |            FILE        | LINE | CHARACTER | BYTE_OFFSET | CATEGORY |  CODE  | SQL_STATE |   COLUMN_NAME        | ROW_NUMBER | ROW_START_LINE |
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    | Field delimiter ',' found while expecting record delimiter '\n'                                                               | @MYTABLE/data1.csv.gz  | 3    | 21        | 76          | parsing  | 100016 | 22000     | "MYTABLE"["QUOTA":3] | 3          | 3              |
    | NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null | @MYTABLE/data3.csv.gz  | 3    | 2         | 62          | parsing  | 100088 | 22000     | "MYTABLE"["NAME":1]  | 3          | 3              |
    | End of record reached while expected to parse column '"MYTABLE"["QUOTA":3]'                                                   | @MYTABLE/data3.csv.gz  | 4    | 20        | 96          | parsing  | 100068 | 22000     | "MYTABLE"["QUOTA":3] | 4          | 4              |
    +-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
    
  • Exécutez la commande COPY en mode validation pour un nombre spécifié de lignes. Dans cet exemple, la première exécution ne rencontre aucune erreur dans le nombre de lignes spécifié et se termine avec succès, affichant les informations telles qu’elles apparaissent lorsqu’elles sont chargées dans la table. La deuxième exécution rencontre une erreur dans le nombre de lignes spécifié et échoue avec l’erreur rencontrée :

    COPY INTO mytable VALIDATION_MODE = 'RETURN_2_ROWS';
    
    +--------------------+----------+-------+
    |        NAME        |    ID    | QUOTA |
    +--------------------+----------+-------+
    | Joe Smith          |  456111  | 0     |
    | Tom Jones          |  111111  | 3400  |
    +--------------------+----------+-------+
    
    COPY INTO mytable VALIDATION_MODE = 'RETURN_3_ROWS';
    
    FAILURE: NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null
      File '@MYTABLE/data3.csv.gz', line 3, character 2
      Row 3, column "MYTABLE"["NAME":1]