Considérations relatives au déchargement de données¶

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 de données. Pour plus d’informations sur ces formats de fichier, voir CREATE FILE FORMAT :

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | 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 = ( 'string1' [ , 'string2' ... ] )

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

-- Source table (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 (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 |
+---+------+--------------+

-- Source table (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 (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 seul fichier¶

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

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 dans 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 dans Parquet avec plusieurs colonnes¶

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¶

Par défaut, lorsque des données de table sont déchargées dans des fichiers Parquet, les colonnes de nombres à point fixe sont déchargées en tant que colonnes DECIMAL, tandis que les colonnes de nombre à virgule flottante sont déchargées en tant que colonnes DOUBLE.

Pour choisir les types de données Parquet pour les ensembles de données déchargées, appelez la fonction CAST , :: dans l’instruction COPY INTO <location> pour convertir des colonnes de table spécifiques en types de données explicites. Une requête dans une instruction COPY INTO <location> permet de sélectionner des colonnes spécifiques à décharger et accepte des fonctions de conversion SQL pour transformer les données des colonnes.

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

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

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

Nombres à virgule flottante tronqués¶

Lorsque des colonnes à nombre de virgule flottante sont déchargées dans des fichiers CSV ou JSON, Snowflake tronque les valeurs à environ (15,9).

Les valeurs sont non tronquées lors du déchargement des colonnes de nombres à virgule flottante dans les fichiers Parquet.