COPY FILES¶

Syntaxe¶

Copier à partir d’une zone de préparation

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM @[<namespace>.]<stage_name>[/<path>/]
  [ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
  [ PATTERN = '<regex_pattern>' ]
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

Copier à partir d’une requête

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

Paramètres requis¶

INTO @[namespace.]stage_name[/path/]

Spécifie l’emplacement cible des fichiers copiés.

• namespace est la base de données ou le schéma dans lequel réside la zone de préparation interne ou externe, sous la forme database_name.schema_name ou schema_name. L’espace de noms est facultatif si une base de données et un schéma sont actuellement utilisés dans la session utilisateur ; sinon, il est obligatoire.

• path est un chemin facultatif, sensible à la casse, dans l’emplacement de stockage Cloud, qui spécifie un ensemble de fichiers à copier à partir de la zone de préparation source ou d’un emplacement spécifique sur la zone de préparation cible. Votre service de stockage dans le Cloud peut appeler le chemin d’accès un préfixe ou un dossier.

Note

• Si un nom de chemin cible ou source comprend des caractères spéciaux ou des espaces, vous devez placer la valeur INTO ... entre guillemets simples.

• Les valeurs de INTO ... doivent être des constantes littérales. Les valeurs ne peuvent pas être des variables SQL.

Paramètres facultatifs¶

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

Spécifie une liste d’un ou plusieurs noms de fichiers séparés par des virgules à copier. Les fichiers doivent déjà être mis en zone de préparation dans l’emplacement source que vous spécifiez dans la commande. Snowflake ignore tous les fichiers spécifiés qui ne peuvent pas être trouvés.

Vous pouvez spécifier un maximum de 1 000 noms de fichiers.

La copie des fichiers à partir de la requête ne prend pas en charge cette option. Au lieu de cela, utilisez la requête pour fournir la liste des noms de fichiers.

Note

Pour définir le chemin d’accès au fichier pour les zones de préparation externes, Snowflake ajoute l’URL de la définition de la zone de préparation à chaque nom de fichier de la liste.

Cependant, Snowflake n’insère pas de séparateur entre le chemin d’accès 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 dans la liste FILES.

PATTERN = 'regex_pattern'

Spécifie un modèle d’expression régulière pour filtrer la liste des fichiers à copier. Cette commande applique l’expression régulière à l’ensemble de l’emplacement de stockage dans la clause FROM.

La copie des fichiers à partir de la requête ne prend pas en charge cette option. Au lieu de cela, utilisez la requête pour faire correspondre le modèle.

Astuce

Pour de meilleures performances, évitez les modèles qui filtrent un grand nombre de fichiers.

DETAILED_OUTPUT = { TRUE | FALSE }

Indique si la sortie de la commande doit résumer les résultats de l’opération de copie ou énumérer chaque fichier copié.

Valeurs:

• Si TRUE, la sortie comprend une ligne pour chaque fichier copié à l’emplacement cible. Une seule colonne nommée file contient le chemin cible (le cas échéant) et le nom de fichier pour chaque fichier copié.

• Si FALSE, la sortie est une seule ligne avec le nombre de fichiers qui ont été copiés.

Par défaut:

TRUE

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum (en fonction des emplacements source et cible) ainsi :

Le privilège USAGE relatif à la base de données et au schéma parents est exigé pour effectuer des opérations sur tout objet d’un schéma.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

• Cette commande ne prend pas en charge les actions suivantes :

  • La copie de fichiers vers ou depuis les zones de préparation de la table.

  • Lors de l’utilisation d’une zone de préparation comme source, la copie de fichiers vers ou depuis les zones de préparation de l”utilisateur.

  • Copie de données conservées dans les classes de stockage dans le Cloud d’archives qui doivent être restaurées avant de pouvoir être récupérées. Ces classes de stockage d’archives comprennent la classe de stockage Amazon S3 Glacier Flexible Retrieval, Glacier Deep Archive, ou Microsoft Azure Archive Storage.

  • Copie de fichiers dont la taille est supérieure à 5GB.

• Considérations relatives à l’exécution de cette commande :

  • Les instructions COPY FILES écrasent tous les fichiers existants dont les noms correspondent à l’emplacement cible. La commande ne supprime pas les fichiers existants qui ne correspondent pas aux noms des fichiers copiés.

  • Si une opération de copie de fichier échoue, Snowflake n’effectue pas de nettoyage automatique.

  • Copie de fichiers à partir de Google Cloud Storage : une instruction COPY FILES peut échouer si la liste d’objets d’une zone de préparation externe comprend un ou plusieurs blobs de répertoire. Un blob de répertoire est un chemin d’accès qui se termine par une barre oblique (/). Dans l’exemple suivant, LIST @<stage>, my_gcs_stage/load/ est un blob de répertoire.

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

    Google crée des blobs de répertoire lorsque vous utilisez la console Google Cloud pour créer un répertoire.

    Pour éviter ce problème et spécifier les fichiers à copier, utilisez l’option PATTERN (pour la copie à partir de la zone de préparation) ou FROM (pour la copie à partir de la requête).

    Pour un exemple, voir Copier des fichiers à l’aide de modèles spéciaux.

• La commande COPY FILES entraîne des coûts de transfert de données et de calcul :

  • Transfert de données : les fournisseurs cloud peuvent facturer les données transférées à partir de leur propre réseau. Pour couvrir ces dépenses, Snowflake facture des frais par octet lorsque vous copiez des fichiers d’une zone de préparation interne de Snowflake vers une zone de préparation externe dans une autre région ou avec un autre fournisseur cloud. Snowflake ne facture pas l’entrée des données (par exemple, lors de la copie de fichiers d’une zone de préparation externe vers une zone de préparation interne).

    Pour plus d’informations sur la facturation par transfert de données, voir Comprendre le coût de transfert de données.

  • Calculer : COPY FILES est une fonctionnalité sans serveur et ne nécessite pas d’entrepôt virtuel. La ligne correspondant à la commande COPY FILES sur votre facture Snowflake n’inclut pas les frais liés aux services Cloud.

    Pour plus d’informations sur la facturation des ressources de calcul, voir Comprendre le coût du calcul.

  Note

  Certaines fonctionnalités de Snowflake, telles que les Native apps et les feuilles de calcul, entraînent des frais de COPY FILES. Par conséquent, vous pouvez voir des frais liés à COPY FILES, même si vous n’avez pas exécuté la commande COPY FILES. Pour plus d’informations sur ces frais, contactez le support Snowflake.

• Snowflake ne conserve pas d’historique des copies de fichiers pour cette commande.

Exemples¶

COPY FILES
  INTO @trg_stage
  FROM @src_stage;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  FILES = ('file1.csv', 'file2.csv');

COPY FILES
  INTO @trg_stage/trg_path/
  FROM @src_stage/src_path/;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*/.*/.*[.]csv[.]gz';

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*sales.*[.]csv';

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt');

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');

-- Create a table with URLs
CREATE TABLE urls(src_file STRING, trg_file STRING);
INSERT INTO urls VALUES ('@src_stage/file.txt', 'new_filename.txt');

-- Insert additional URLs here
COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls);

COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');

COPY FILES
  INTO @trg_stage
  FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');