PUT¶
Charge un ou plusieurs fichiers de données d’un système de fichiers local dans une zone de préparation interne.
Après avoir chargé des fichiers dans une zone de préparation interne, vous pouvez charger les données des fichiers dans une table à l’aide de la commande COPY INTO <table>.
Note
PUT ne prend pas en charge le chargement de fichiers dans une zone de préparation externe. Pour charger des fichiers dans une zone de préparation externe, utilisez les utilitaires fournis par votre service Cloud.
Le pilote ODBC prend en charge PUT avec les comptes Snowflake hébergés sur les plateformes suivantes :
Amazon Web Services
Google Cloud
Microsoft Azure
- Voir aussi :
GET , LIST , REMOVE , COPY FILES , CREATE STAGE , Vue d’ensemble du chargement de données
Syntaxe¶
PUT file://<absolute_path_to_file>/<filename> internalStage
[ PARALLEL = <integer> ]
[ AUTO_COMPRESS = TRUE | FALSE ]
[ SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE ]
[ OVERWRITE = TRUE | FALSE ]
Où :
internalStage ::= @[<namespace>.]<int_stage_name>[/<path>] | @[<namespace>.]%<table_name>[/<path>] | @~[/<path>]
Paramètres requis¶
file://absolute_path_to_file/filename
Spécifie l’URI pour les fichiers de données sur la machine cliente, où :
absolute_path_to_file
est le chemin du répertoire local vers les fichiers à charger.filename
est le nom du fichier à charger. Vous pouvez utiliser des caractères génériques (*
,?
) pour charger plusieurs fichiers. Si le chemin d’accès au répertoire ou le nom du fichier contient des caractères spéciaux ou des espaces, le fichier entier URI doit être placé entre guillemets simples.Attention
Soyez prudent lorsque vous sélectionnez plusieurs fichiers à l’aide d’une requête PUT. Les requêtes PUT qui correspondent à grand nombre de fichiers peuvent avoir des conséquences importantes en termes de coût et de performance.
Le formatage de l’URI diffère selon le système d’exploitation de votre client.
- Linux/macOS:
Indiquez le chemin d’accès absolu au fichier à partir du répertoire racine (
/
). Par exemple, pour un fichier nommémy-data.csv
utilisezfile:///my/file/path/my-data.csv
.- Windows:
Indiquez le chemin d’accès absolu à partir de la racine du lecteur où se trouvent le ou les fichiers. Par exemple, pour un fichier nommé
my-data.csv
utilisezfile://C:temp\my-data.csv
.Si le chemin d’accès au fichier contient des caractères spéciaux, vous devez le mettre entièrement entre guillemets simples et remplacer le séparateur de lecteur et de chemin d’accès de type barre oblique arrière par une barre oblique avant (
/
). Par exemple, pour un fichier nommémy$data.csv
, utilisez :'file://C:/temp/my$data.csv'
.
Note
Snowflake ne prend pas en charge les fichiers tar (tape archive).
internalStage
Spécifie l’emplacement de la zone de préparation interne dans laquelle charger les fichiers :
@[namespace.]int_stage_name[/path]
Les fichiers sont chargés dans la zone de préparation interne nommée spécifiée.
@[namespace.]%table_name[/path]
Les fichiers sont chargés dans la zone de préparation de la table spécifiée.
@~[/path]
Les fichiers sont chargés dans la zone de préparation de l’utilisateur actuel.
Où :
namespace
est la base de données ou le schéma qui contient la zone de préparation interne ou la table interne nommée. Il est facultatif si une base de données et un schéma sont utilisés dans la session.path
est un chemin facultatif sensible à la casse pour les fichiers de l’emplacement de stockage cloud qui limite l’accès à un ensemble de fichiers. Les chemins sont appelés préfixes ou dossiers selon les services de stockage Cloud.
Note
Si le nom ou le chemin de la zone de préparation comprend des espaces ou des caractères spéciaux, placez-le entre guillemets simples. Par exemple, utilisez
'@"my stage"'
pour une zone de préparation nommée"my stage"
.
Paramètres facultatifs¶
PARALLEL = integer
Spécifie le nombre de threads à utiliser pour charger les fichiers. Snowflake charge des lots de fichiers de données distincts en fonction de leur taille :
Les fichiers dont la taille est inférieure à 64 MB (compressés ou non) sont mis en zone de préparation en parallèle sous forme de fichiers individuels.
Les fichiers plus volumineux sont automatiquement divisés en plusieurs parties, stockés en même temps et réunis dans la zone de préparation cible. Un seul thread peut charger plusieurs parties.
Augmenter le nombre de threads peut améliorer les performances lors du chargement de fichiers volumineux.
Valeurs prises en charge : toute valeur entière de
1
(pas de parallélisme) à99
(utilisez 99 threads pour charger des fichiers).Par défaut :
4
Note
Une limite 16 MB s’applique aux anciennes versions des pilotes Snowflake, notamment :
Les versions de pilotes JDBC antérieures à la version 3.12.1.
Les versions de pilotes ODBC antérieures à la version 2.20.5.
Versions du connecteur Python antérieures à la version 2.2.0.
AUTO_COMPRESS = TRUE | FALSE
Indique si Snowflake utilise gzip pour compresser les fichiers pendant le chargement :
TRUE
: Snowflake compresse les fichiers (s’ils ne sont pas déjà compressés).FALSE
: Snowflake ne compresse pas les fichiers.
Cette option ne prend pas en charge les autres types de compression. Pour utiliser un type de compression différent, compressez le fichier séparément avant d’exécuter la commande PUT. Ensuite, identifiez le type de compression à l’aide de l’option
SOURCE_COMPRESSION
.Assurez-vous que votre dossier local dispose de suffisamment d’espace pour permettre à Snowflake de compresser les fichiers de données avant de les mettre en zone de préparation. Si nécessaire, définissez la variable d’environnement
TEMP
,TMPDIR
ouTMP
de votre système d’exploitation pour qu’elle pointe vers un dossier local contenant davantage d’espace disponible.Par défaut :
TRUE
SOURCE_COMPRESSION = AUTO_DETECT | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
Spécifie la méthode de compression utilisée sur les fichiers déjà compressés qui sont stockés actuellement :
Valeurs prises en charge
Remarques
AUTO_DETECT
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 par Brotli, utilisez explicitement
BROTLI
au lieu deAUTO_DETECT
.GZIP
Ne prend pas en charge le format de fichier
*.tar.gz
.BZ2
Ne prend pas en charge le format de fichier
*.tar.bz2
.BROTLI
Doit être utilisé si vous chargez des fichiers compressés par 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 n’ont pas été compressés.
Par défaut :
AUTO_DETECT
Note
Snowflake utilise cette option pour détecter la façon dont les fichiers de données ont été compressés afin qu’ils puissent être décompressés et que les données puissent être extraites pour être chargées ; il n’utilise pas cette option pour compresser les fichiers.
Il n’est actuellement pas possible de charger des fichiers qui ont été compressés avec d’autres utilitaires.
OVERWRITE = TRUE | FALSE
Spécifie si Snowflake écrase un fichier existant portant le même nom lors du chargement :
TRUE
: un fichier existant portant le même nom est écrasé.FALSE
: un fichier existant portant le même nom n’est pas écrasé.Snowflake effectue une opération LIST sur la zone de préparation en arrière-plan, ce qui peut affecter les performances de l’opération PUT.
Si les tentatives d’opération PUT sur un fichier échouent parce qu’il existe un fichier portant le même nom dans la zone de préparation cible, vous pouvez entreprendre les actions suivantes :
Chargez les données du fichier existant dans une ou plusieurs tables, et supprimez le fichier de la zone de préparation. Puis effectuez une opération PUT sur un fichier avec des données nouvelles ou mises à jour dans la zone de préparation.
Renommez le fichier local, puis tentez à nouveau l’opération PUT.
Définissez
OVERWRITE = TRUE
dans l’instruction PUT. Ne le faites que s’il est possible d’écraser le fichier existant (mis en zone de préparation) portant le même nom.
Si votre compte Snowflake est hébergé sur Google Cloud, les instructions PUT ne sont pas reconnues lorsque le paramètre OVERWRITE est défini sur TRUE. Une opération PUT remplace toujours tous les fichiers existants dans la zone de préparation cible par les fichiers locaux que vous chargez.
Les clients suivants prennent en charge l’option OVERWRITE pour les comptes Snowflake hébergés sur Amazon Web Services ou sur Microsoft Azure :
SnowSQL
Pilote ODBC de Snowflake
Pilote JDBC de Snowflake
Connecteur Snowflake pour Python
Valeurs prises en charge : TRUE, FALSE.
Par défaut :
FALSE
.
Notes sur l’utilisation¶
La commande ne peut pas être exécutée à partir de la page Worksheets
dans aucune des interfaces Web de Snowflake ; utilisez plutôt le client SnowSQL ou Pilotes pour charger les fichiers de données, ou consultez la documentation d’un client Snowflake spécifique pour vérifier si cette commande est prise en charge.
Vous pouvez également utiliser l’UI Snowsight pour charger des fichiers dans une zone de préparation interne.
Les modèles d’utilisation de caractères génériques, comme les caractères génériques, sont pris en charge sauf si les fichiers correspondant au modèle ont des chemins d’accès divergents. La commande ne prend pas en charge le chargement de plusieurs fichiers avec des chemins d’accès à des répertoires divergents, car Snowflake ne préserve pas la structure des répertoires du système de fichiers lors du chargement de fichiers dans votre zone de préparation.
Par exemple, l’instruction PUT suivante renvoie une erreur, car il n’est pas possible de spécifier plusieurs fichiers dans des sous-répertoires imbriqués.
PUT file:///tmp/data/** @my_int_stage AUTO_COMPRESS=FALSE;
La commande ne crée pas et ne renomme pas de fichiers.
Tous les fichiers stockés sur des zones de préparation internes pour les opérations de chargement et de déchargement de données sont automatiquement chiffrés à l’aide d’un chiffrement fort AES-256 côté serveur. Par défaut, Snowflake fournit un chiffrement supplémentaire côté client avec une clé de 128 bits (avec la possibilité de configurer une clé de 256 bits). Pour plus d’informations, consultez Types de chiffrement pour les zones de préparation internes.
La commande ignore tous les fichiers en double que vous tentez de charger dans la même zone de préparation. Dans ce contexte, un fichier dupliqué est un fichier non modifié portant le même nom qu’un fichier déjà en zone de préparation.
Pour écraser un fichier déjà mis en zone de préparation, vous devez modifier le fichier que vous chargez pour qu’il soit différent du fichier en zone de préparation, ce qui se traduit par une nouvelle somme de contrôle pour le fichier que vous venez de mettre en zone de préparation.
Pour les commandes PUT et GET, un EXECUTION_STATUS de
success
dans l”QUERY_HISTORY ne signifie pas que les fichiers de données ont été importés correctement. Au lieu de cela, le statut indique que Snowflake a reçu l’autorisation de procéder au transfert de fichier.
Astuce
Pour des raisons de sécurité, la commande expire après une période de temps définie. Cela peut se produire lors du chargement de fichiers de données volumineux et non compressés. Pour éviter tout problème de délai d’attente, nous vous recommandons de compresser les fichiers de données volumineux en utilisant l’un des types de compression pris en charge avant de charger les fichiers. Ensuite, spécifiez le type de compression pour les fichiers en utilisant l’option SOURCE_COMPRESSION
.
Vous pouvez également envisager d’augmenter la valeur de l’option PARALLEL
, ce qui peut améliorer les performances lors du chargement de fichiers de données volumineux.
De plus, pour profiter des opérations parallèles lors du chargement des données dans des tables (en utilisant la commande COPY INTO <table>), nous recommandons d’utiliser des fichiers de données dont la taille varie d’environ 100 à 250 MB compressés. Si vos fichiers de données sont plus volumineux, pensez à utiliser un outil tiers pour les diviser en fichiers plus petits avant de les compresser et de les charger.
Exemples¶
Linux et macOS¶
Charger un fichier dans une zone de préparation interne
Chargez un fichier nommé mydata.csv
dans le répertoire /tmp/data
dans une zone de préparation interne nommée my_int_stage
:
PUT file:///tmp/data/mydata.csv @my_int_stage;
Charger un fichier dans une zone de préparation de table
Chargez un fichier nommé orders_001.csv
dans le répertoire /tmp/data
dans la zone de préparation de la table orderstiny_ext
, avec la compression automatique des données désactivée :
PUT file:///tmp/data/orders_001.csv @%orderstiny_ext
AUTO_COMPRESS = FALSE;
Charger plusieurs fichiers dans une zone de préparation interne
Utilisez des caractères génériques dans le nom du fichier pour charger plusieurs fichiers :
PUT file:///tmp/data/orders_*01.csv @my_int_stage
AUTO_COMPRESS = FALSE;
Spécifier un chemin d’accès à un fichier avec des caractères spéciaux
Mettez entre guillemets simples le chemin d’accès à un fichier contenant des caractères spéciaux ou des espaces :
PUT 'file:///tmp/data/orders 001.csv' @my_int_stage
AUTO_COMPRESS = FALSE;
Windows¶
Charger un fichier dans la zone de préparation de l’utilisateur actuel
Chargez un fichier nommé mydata.csv
dans le répertoire C:\temp\data
dans la zone de préparation de l’utilisateur actuel, avec la compression de données automatique activée :
PUT file://C:\temp\data\mydata.csv @~
AUTO_COMPRESS = TRUE;
Spécifier un chemin d’accès à un fichier avec des caractères spéciaux
Pour spécifier un chemin d’accès à un fichier Windows avec des caractères spéciaux, vous devez mettre le chemin entre guillemets simples et remplacer les barres obliques arrière par des barres obliques avant.
Dans cet exemple, le nom de fichier contient un espace (my data.csv
) :
PUT 'file://C:/temp/data/my data.csv' @my_int_stage
AUTO_COMPRESS = TRUE;