Considérations relatives au déchargement des données

Ce chapitre fournit des bonnes pratiques, des lignes directrices générales et des considérations importantes concernant le déchargement de données depuis une table. Il est destiné à simplifier l’exportation des données depuis des tables Snowflake vers des fichiers en zones de préparation à l’aide de la commande COPY INTO <emplacement>.

Dans ce chapitre :

Chaînes vides et valeurs NULL

Une chaîne vide est une chaîne de caractères de longueur nulle ou sans caractères, alors que les valeurs NULL représentent une absence de données. Dans les fichiers CSV , une valeur NULL est généralement représentée par deux délimiteurs successifs (par exemple ,,) pour indiquer que le champ ne contient aucune donnée. Cependant, vous pouvez utiliser des valeurs de chaîne pour indiquer NULL (par exemple null) ou toute chaîne unique. Une chaîne vide est généralement représentée par une chaîne vide entre guillemets (par exemple ,'',) pour indiquer que la chaîne contient zéro caractère.

Les options de format de fichier suivantes vous permettent de différencier les chaînes vides des valeurs NULL lors du déchargement ou du chargement des données. Pour plus d’informations sur ces formats de fichier, voir CREATE FILE FORMAT :

FIELD_OPTIONALLY_ENCLOSED_BY = 'caractère' | NONE

Utilisez cette option pour inclure des chaînes dans le caractère spécifié : guillemets simples ('), guillemets doubles (") ou NONE.

Il n’est pas nécessaire de mettre entre guillemets les valeurs de chaîne pendant le déchargement des données. La commande d’emplacement COPY INTO peut décharger des valeurs de chaîne vides sans les mettre entre guillemets, lorsque l’option EMPTY_FIELD_AS_NULL est définie sur FALSE. Si l’option EMPTY_FIELD_AS_NULL est TRUE (ce qui est interdit), alors les chaînes vides et les valeurs NULL ne peuvent être distinguées dans le fichier de sortie.

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", évitez les guillemets doubles comme suit : ""A"".

Par défaut : NONE

EMPTY_FIELD_AS_NULL = TRUE | FALSE
  • Lors du déchargement de données de chaîne vide des tables, sélectionnez l’une des options suivantes :

    • Préféré : mettez les chaînes entre guillemets en sélectionnant l’option FIELD_OPTIONALLY_ENCLOSED_BY afin de différencier les chaînes vides des valeurs NULLs dans les fichiers de sortie CSV.

    • Ne mettez pas les champs de chaîne entre guillemets en définissant l’option FIELD_OPTIONALLY_ENCLOSED_BY sur NONE (par défaut), et définissez la valeur EMPTY_FIELD_AS_NULL sur FALSE pour décharger les chaînes vides en tant que champs vides.

      Important

      Si vous choisissez cette option, assurez-vous de spécifier une chaîne de remplacement pour les données NULL en utilisant l’option NULL_IF pour distinguer les valeurs NULL des chaînes vides dans le fichier de sortie. Si vous choisissez ultérieurement de charger des données à partir des fichiers de sortie, vous spécifierez la même valeur NULL_IF pour identifier les valeurs NULL dans les fichiers de données.

  • Lors du chargement des données dans des tables, utilisez cette option pour spécifier s’il faut insérer SQL NULL pour les champs vides dans un fichier d’entrée. 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 de données STRING. Pour les autres types de colonne, la commande COPY produit une erreur.

Par défaut : TRUE

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

Lors du déchargement des données à partir de tables, Snowflake convertit les valeurs NULL SQL vers la première valeur de la liste. Veillez à spécifier une valeur à interpréter comme NULL. Par exemple, si vous déchargez des données dans un fichier qui sera lu par un autre système, veillez à spécifier une valeur qui sera interprétée comme NULL par ce système.

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

Exemple : déchargement et chargement des données avec guillemets de fermeture

Dans l’exemple suivant, un ensemble de données est déchargé de la table null_empty1 vers la zone de préparation de l’utilisateur. Le fichier de données de sortie est ensuite utilisé pour charger des données dans la table null_tempty2 :

-- Source table (:code:`null_empty1`) contents
+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

-- Create a file format that describes the data and the guidelines for processing it
create or replace file format my_csv_format
  field_optionally_enclosed_by='0x27' null_if=('null');

-- Unload table data into a stage
copy into @mystage
  from null_empty1
  file_format = (format_name = 'my_csv_format');

-- Output the data file contents
1,'null','NULL value'
2,'','Empty string'

-- Load data from the staged file into the target table (:code:`null_empty2`)
copy into null_empty2
    from @mystage/data_0_0_0.csv.gz
    file_format = (format_name = 'my_csv_format');

select * from null_empty2;

+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

Exemple : déchargement et chargement des données sans guillemets de fermeture

Dans l’exemple suivant, un ensemble de données est déchargé de la table null_empty1 vers la zone de préparation de l’utilisateur. Le fichier de données de sortie est ensuite utilisé pour charger des données dans la table null_tempty2 :

-- Source table (:code:`null_empty1`) contents
+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

-- Create a file format that describes the data and the guidelines for processing it
create or replace file format my_csv_format
  empty_field_as_null=false null_if=('null');

-- Unload table data into a stage
copy into @mystage
  from null_empty1
  file_format = (format_name = 'my_csv_format');

-- Output the data file contents
1,null,NULL value
2,,Empty string

-- Load data from the staged file into the target table (:code:`null_empty2`)
copy into null_empty2
    from @mystage/data_0_0_0.csv.gz
    file_format = (format_name = 'my_csv_format');

select * from null_empty2;

+---+------+--------------+
| i | V    | D            |
|---+------+--------------|
| 1 | NULL | NULL value   |
| 2 |      | Empty string |
+---+------+--------------+

Déchargement dans un fichier unique

Par défaut, les instructions d’emplacement COPY INTO séparent les données de table en un ensemble de fichiers de sortie pour permettre des opérations parallèles. La taille maximale de chaque fichier est définie à l’aide de l’option de copie MAX_FILE_SIZE. La valeur par défaut est 16000000 (16 MB), mais peut être augmentée pour les fichiers plus volumineux. La taille de fichier maximale prise en charge est de 5 GB pour les zones de préparation Amazon S3, Google Cloud Storage et Microsoft Azure.

Pour conserver les données dans un seul fichier de sortie (au risque de réduire les performances), spécifiez l’option de copie SINGLE = true dans votre instruction. En option, vous pouvez indiquer un nom pour le fichier dans le chemin.

Note

Si l’option COMPRESSION est définie sur « true », indiquez un nom de fichier avec l’extension de fichier correspondante pour la méthode de compression afin que le fichier de sortie puisse être décompressé. Par exemple, indiquez l’extension de fichier GZ si la méthode de compression GZIP est sélectionnée.

Par exemple, déchargez les données de la table mytable dans un fichier unique nommé myfile.csv dans une zone de préparation nommée. Augmentez la limite MAX_FILE_SIZE pour héberger le grand ensemble de données :

copy into @mystage/myfile.csv.gz from mytable
file_format = (type=csv compression='gzip')
single=true
max_file_size=4900000000;

Déchargement d’une table relationnelle vers JSON

Vous pouvez utiliser la fonction OBJECT_CONSTRUCT avec la commande COPY pour convertir les lignes d’une table rationnelle en une colonne unique VARIANT et décharger les lignes vers un fichier.

Par exemple :

-- Create a table
CREATE OR REPLACE TABLE mytable (
 id number(8) NOT NULL,
 first_name varchar(255) default NULL,
 last_name varchar(255) default NULL,
 city varchar(255),
 state varchar(255)
);

-- Populate the table with data
INSERT INTO mytable (id,first_name,last_name,city,state)
 VALUES
 (1,'Ryan','Dalton','Salt Lake City','UT'),
 (2,'Upton','Conway','Birmingham','AL'),
 (3,'Kibo','Horton','Columbus','GA');

-- Unload the data to a file in a stage
COPY INTO @mystage
 FROM (SELECT OBJECT_CONSTRUCT('id', id, 'first_name', first_name, 'last_name', last_name, 'city', city, 'state', state) FROM mytable)
 FILE_FORMAT = (TYPE = JSON);

-- The COPY INTO location statement creates a file named data_0_0_0.json.gz in the stage.
-- The file contains the following data:

{"city":"Salt Lake City","first_name":"Ryan","id":1,"last_name":"Dalton","state":"UT"}
{"city":"Birmingham","first_name":"Upton","id":2,"last_name":"Conway","state":"AL"}
{"city":"Columbus","first_name":"Kibo","id":3,"last_name":"Horton","state":"GA"}

Déchargement d’une table relationnelle vers Parquet avec des colonnes multiples

Vous pouvez décharger des données d’une table relationnelle dans un fichier Parquet à plusieurs colonnes en utilisant une instruction SELECT en entrée de l’instruction COPY. L’instruction SELECT spécifie les données de colonne de la table relationnelle à inclure dans le fichier non chargé. Utilisez l’option de copie HEADER = TRUE pour inclure les en-têtes de colonne dans les fichiers de sortie.

Par exemple, décharger les lignes de trois colonnes (id, name, start_date) de la table mytable dans un ou plusieurs fichiers qui ont le format d’appellation myfile.parquet :

COPY INTO @mystage/myfile.parquet FROM (SELECT id, name, start_date FROM mytable)
  FILE_FORMAT=(TYPE='parquet')
  HEADER = TRUE;

Conversion explicite de colonnes numériques en types de données Parquet

Les requêtes dans les instructions COPY INTO <location> prennent en charge la syntaxe et la sémantique des instructions SELECT pour interroger des colonnes de table Snowflake spécifiques à décharger. Convertissez les données des colonnes numériques en types de données spécifiques à l’aide de la fonction CAST , :: pour choisir explicitement le type de données Parquet pour les données déchargées.

La table suivante convertit les types de données numériques Snowflake en types de données physiques et logiques Parquet :

Type de données logiques Snowflake

Type de données physiques Parquet

Type de données logiques Parquet

TINYINT

INT32

INT(8)

SMALLINT

INT32

INT(16)

INT

INT32

INT(32)

BIGINT

INT64

INT(64)

FLOAT

FLOAT

N/A

DOUBLE

DOUBLE

N/A

L’exemple suivant montre une instruction COPY INTO <location> qui convertit les données numériques de chaque colonne déchargée en un type de données différent pour choisir explicitement les types de données dans les fichiers Parquet :

COPY INTO @mystage
FROM (SELECT CAST(C1 AS TINYINT) ,
             CAST(C2 AS SMALLINT) ,
             CAST(C3 AS INT),
             CAST(C4 AS BIGINT) FROM mytable)
FILE_FORMAT=(TYPE=PARQUET);