Catégories :

Commandes DML - Chargement des données

PUT

Charge des fichiers de données (c.-à-d. des zones de préparation) à partir d’un répertoire/dossier local sur une machine cliente vers l’une des zones de préparation suivantes de Snowflake :

  • Zone de préparation interne nommée.

  • Zone de préparation pour une table spécifiée.

  • Zone de préparation interne pour l’utilisateur actuel.

Une fois les fichiers mis en zone de préparation, les données contenues dans les fichiers peuvent être chargées dans une table à l’aide de la commande COPY INTO <table>.

Note

  • PUT ne prend pas en charge le chargement de fichiers vers des zones de préparation externes. Pour charger des fichiers vers des zones de préparation externes, utilisez les utilitaires fournis par le service Cloud.

  • Les clients Snowflake suivants ne prennent pas en charge PUT :

    • Pilote Go Snowflake

    • Pilote .NET

    • Pilote Node.js

  • Le pilote ODBC prend en charge PUT avec les comptes Snowflake hébergés sur les plateformes suivantes :

    • Amazon Web Services (en utilisant le pilote ODBC version 2.17.5 et supérieure).

    • Google Cloud Platform (en utilisant le pilote ODBC version 2.21.5 et supérieure).

    • Microsoft Azure (en utilisant le pilote ODBC version 2.20.2 et supérieure).

Voir aussi :

GET , LIST , REMOVE

Syntaxe

PUT file://<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://chemin_fichier/nom_fichier

Spécifie l’URI pour le(s) fichier(s) de données sur la machine cliente, où :

  • chemin_fichier est le chemin du répertoire local vers le(s) fichier(s) à charger. Si les fichiers sont situés dans le répertoire racine (ou sous-répertoire) de la machine cliente :

    Linux/Mac

    Vous devez inclure la barre oblique initiale dans le chemin (par ex. file:///tmp/load).

    Windows

    Vous devez inclure le lecteur et la barre oblique inverse dans le chemin (par ex. file://C:\temp\load).

  • nom_fichier est le nom du ou des fichiers à charger. Les caractères génériques (*, ?) sont pris en charge pour permettre le chargement de plusieurs fichiers dans un répertoire.

L’URI peut être délimitée par des guillemets simples, ce qui permet l’insertion de caractères spéciaux, y compris des espaces, dans les noms de répertoire et de fichier ; cependant, le séparateur de lecteur et de chemin est une barre oblique (/) pour tous les systèmes d’exploitation pris en charge (par exemple 'file://C:/temp/load data' pour un chemin dans Windows contenant un répertoire nommé load data).

internalStage

Spécifie l’emplacement dans Snowflake où charger les fichiers :

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

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

@[espace_noms.]%nom_table[/chemin]

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

@~[/chemin]

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

Où :

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

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

La chaîne peut être délimitée par des guillemets simples, ce qui permet d’insérer des caractères spéciaux, y compris des espaces, dans les noms de lieux (par exemple, '@"my stage"' pour une zone de préparation nommée "my stage").

Paramètres facultatifs

PARALLEL = entier

Spécifie le nombre de threads à utiliser pour charger les fichiers. Le processus de chargement sépare les lots de fichiers de données par taille :

  • Les petits fichiers (< 64 MB compressés ou non compressés) 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 (plutôt que 64 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 : les fichiers sont compressés (s’ils ne le sont pas déjà).

  • FALSE : les fichiers ne sont pas compressés (les fichiers sont chargés tels quels).

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 ou TMP 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 via Brotli, utilisez explicitement BROTLI au lieu de AUTO_DETECT.

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.

Par défaut : AUTO_DETECT

Note

Snowflake utilise cette option pour détecter comment les fichiers de données ont été compressés afin qu’ils puissent être décompressés et les données extraites pour le chargement ; cette option n’est pas utilisée pour compresser des fichiers.

Le chargement de fichiers qui ont été compressés avec d’autres utilitaires (par ex. lzip, lzma, lzop, et xz) n’est pas pris en charge actuellement.

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

Si vous tentez de PUT un fichier mais que vous ne le pouvez pas car un fichier portant le même nom existe déjà dans la zone de préparation, vous pouvez effectuer l’une des opérations suivantes :

  • Attendez que les données du fichier existant soient chargées, puis réessayez PUT.

  • Renommez le fichier que vous souhaitez PUT.

  • Définissez OVERWRITE = TRUE. Ne le faites que s’il est vraiment sûr d’écraser un fichier avec des données qui n’ont peut-être pas encore été chargées dans Snowflake.

Les plates-formes suivantes prennent en charge l’option OVERWRITE :

  • Amazon AWS

  • Microsoft Azure.

GCP, la plate-forme Cloud de Google, ne prend pas en charge OVERWRITE=FALSE. Sur GCP, la commande PUT charge toujours le fichier, même s’il existe un fichier du même nom et que OVERWRITE est défini sur false.

Les pilotes et connecteurs suivants prennent en charge l’option OVERWRITE :

  • Pilote ODBC de Snowflake.

  • Pilote JDBC de Snowflake.

  • Connecteur Python de Snowflake.

L’option OVERWRITE est également prise en charge dans SnowSQL.

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 Worksheet tab de l’interface Web de Snowflake ; utilisez plutôt le client SnowSQL pour charger les fichiers de données, ou consultez la documentation du client Snowflake spécifique pour vérifier si cette commande est prise en charge.

  • Les motifs d’utilisation de caractères génériques ne sont pas pris en charge.

  • La commande ne crée pas ou ne renomme pas les fichiers ; le préfixe (s’il y en a un) dans la zone de préparation interne spécifiée est destinée aux fichiers existants, pas aux nouveaux fichiers.

  • Les fichiers chargés sont automatiquement chiffrés avec des clés de 128 ou 256 bits. Le paramètre de compte CLIENT_ENCRYPTION_KEY_SIZE indique la taille de la clé utilisée pour chiffrer les fichiers.

  • 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à stocké.

    Pour écraser un fichier déjà stocké, vous devez modifier le fichier que vous chargez pour qu’il soit différent du fichier stocké, ce qui se traduit par une nouvelle somme de contrôle pour le fichier que vous venez de stocker.

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 gros fichiers de données 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 10 à 100 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

Chargez un fichier nommé mydata.csv dans le répertoire /tmp/data (dans un environnement Linux ou macOS) vers une zone de préparation interne nommée my_int_stage :

PUT file:///tmp/data/mydata.csv @my_int_stage;

Chargez un fichier nommé orders_001.csv dans le répertoire /tmp/data (dans un environnement Linux ou macOS) 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;

Même exemple que ci-dessus, mais en utilisant des caractères génériques dans le nom du fichier pour charger plusieurs fichiers :

PUT file:///tmp/data/orders_*01.csv @%orderstiny_ext AUTO_COMPRESS=FALSE;

Chargez un fichier nommé mydata.csv dans le répertoire C:\temp\data (dans un environnement Windows) dans la zone de préparation de l’utilisateur actuel, avec la compression automatique des données activée :

PUT file://C:\temp\data\mydata.csv @~ AUTO_COMPRESS=TRUE;