COPY INTO

S’applique à : Databricks SQL Databricks Runtime

Charge des données à partir d’un emplacement de fichier dans une table Delta. Cette opération peut être tentée à nouveau et est sans effet – Les fichiers déjà chargés dans l’emplacement source sont ignorés. Cela vaut même si les fichiers ont été modifiés depuis leur chargement. Pour obtenir des exemples, consultez Modèles courants de chargement de données utilisant COPY INTO.

Syntaxe

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

Paramètres

• target_table

  Identifie une table Delta existante. target_table ne doit pas inclure une spécification temporelle.

  Si le nom de la table est fourni sous la forme d’un emplacement, par exemple delta.`/path/to/table` , le catalogue Unity peut régir l’accès aux emplacements dans utilisant sur lesquels vous écrivez. Vous pouvez écrire dans un emplacement externe en :

  • Définissant l’emplacement en tant qu’emplacement externe et disposant des autorisations WRITE FILES sur cet emplacement externe.
  • Disposant des autorisations WRITE FILES sur des informations d’identification de stockage nommées qui fournissent l’autorisation d’écrire dans un emplacement à l’aide de COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>)

  Pour obtenir d’autres détails, consultez Se connecter au stockage d’objets cloud à l’aide de Unity Catalog.

• BY POSITION | ( col_name [ , <col_name> … ] )

  Fait correspondre aux colonnes sources les colonnes de table cible par position ordinale. Le cast de type des colonnes mises en correspondance est effectué automatiquement.

  Ce paramètre est pris en charge uniquement pour le format de fichier CSV sans en-tête. Vous devez spécifier la valeur FILEFORMAT = CSV. FORMAT_OPTIONS doit également être défini sur ("headers" = "false") (FORMAT_OPTIONS ("headers" = "false") est la valeur par défaut).

  Options de syntaxe 1 : BY POSITION

  • Fait automatiquement correspondre aux colonnes sources les colonnes de table cible par position ordinale.
    • La correspondance de nom par défaut n’est pas utilisée pour la correspondance.
    • Les colonnes IDENTITY et les colonnes GENERATED de la table cible sont ignorées lors de la correspondance aux colonnes sources.
    • Si le nombre de colonnes sources n’est pas égal à celui des colonnes de la table cible filtrée, COPY INTO génère une erreur.

  Options de syntaxe 2 : ( col_name [ , <col_name> ... ] )

  • Fait correspondre aux colonnes sources les colonnes de la table cible spécifiées par position ordinale relative à l’aide d’une liste de noms de colonne de la table cible entre parenthèses, séparés par des virgules.
    • L’ordre des colonnes de table d’origine et les noms de colonnes ne sont pas utilisés pour la correspondance.
    • Les colonnes IDENTITY et les colonnes GENERATED ne peuvent pas être spécifiées dans la liste des noms de colonne, sinon COPY INTO génère une erreur.
    • Les colonnes spécifiées ne peuvent pas être dupliquées.
    • Quand le nombre de colonnes sources n’est pas égal à celui des colonnes de la table spécifiée, COPY INTO génère une erreur.
    • Pour les colonnes non spécifiées dans la liste des noms de colonne, COPY INTO attribue les valeurs par défaut, le cas échéant, sinon il attribue NULL. Si une colonne ne peut accepter la valeur Null, COPY INTO génère une erreur.

• source

  Emplacement du fichier à partir duquel charger les données. Les fichiers de cet emplacement doivent avoir le format spécifié dans FILEFORMAT. L’emplacement est fourni sous la forme d’un URI.

  L’accès à l’emplacement source peut être fourni via :

  • credential_name

    Nom facultatif des informations d’identification utilisées pour accéder à l’emplacement de stockage ou y écrire des données. Vous utilisez ces informations d'identification uniquement si l'emplacement du fichier n'est pas inclus dans un emplacement externe. Consultez credential_name.

  • Informations d’identification temporaires inline.

  • Définition de l’emplacement source en tant qu’emplacement externe et disposant des autorisations READ FILES sur l’emplacement externe via le catalogue Unity.

  • Utilisation d’informations d’identification de stockage nommées avec des autorisations READ FILES qui fournissent l’autorisation de lire à partir d’un emplacement via le catalogue Unity.

  Vous n’avez pas besoin de fournir des informations d’identification incluses ou nommées si le chemin d’accès est déjà défini en tant qu’emplacement externe que vous avez l’autorisation d’utiliser. Consultez Créer un emplacement externe pour connecter le stockage cloud à Azure Databricks pour plus de détails.

  Remarque

  Si le chemin du fichier source est un chemin racine, veuillez ajouter une barre oblique (/) à la fin du chemin du fichier, par exemple, s3://my-bucket/.

  Les options d’informations d’identification acceptées sont les suivantes :

  • AZURE_SAS_TOKEN pour ADLS Gen2 et Stockage Blob Azure
  • AWS_ACCESS_KEY, AWS_SECRET_KEY et AWS_SESSION_TOKEN pour AWS S3

  Les options de chiffrement acceptées sont les suivantes :

  • TYPE = 'AWS_SSE_C' et MASTER_KEY pour AWS S3

Consultez Charger des données à l’aide de COPY INTO avec des informations d’identification temporaires.

• SELECT expression_list

  Sélectionne les colonnes ou expressions spécifiées dans les données sources avant de les copier dans la table Delta. Vous pouvez utiliser n’importe quelle expression acceptant des instructions SELECT, y compris les opérations de fenêtre. Vous pouvez utiliser les expressions d'agrégation uniquement pour les agrégats globaux ; vous ne pouvez pas utiliser GROUP BY sur des colonnes avec cette syntaxe.

• FILEFORMAT = data_source

  Format des fichiers source à charger. Valeurs possibles : CSV, JSON, AVRO, ORC, PARQUET, TEXT, BINARYFILE.

• VALIDATE

  S’applique à : Databricks SQL Databricks Runtime 10.4 LTS et ultérieur

  Les données à charger dans une table sont validées, mais ne sont pas écrites dans la table. Ces validations comprennent :

  • Indique si les données peuvent être analysées.
  • Indique si le schéma correspond à celui de la table ou si le schéma doit évoluer.
  • Indique si toutes les contraintes d’acceptation de valeurs Null et de validation sont respectées.

  Par défaut, toutes les données à charger sont validées. Vous pouvez fournir un certain nombre de lignes à valider avec le mot cléROWS, par exemple VALIDATE 15 ROWS. L'instruction COPY INTO renvoie un aperçu des données de 50 lignes ou moins, lorsqu'un nombre inférieur à 50 est utilisé avec le mot clé ROWS).

• FILES

  Liste des noms de fichiers à charger, avec une limite de 1 000 fichiers. Impossible à spécifier avec PATTERN.

• PATTERN

  Modèle Glob qui identifie les fichiers à charger à partir du répertoire source. Impossible à spécifier avec FILES.

  Modèle	Description
  ?	Correspond à n’importe quel caractère unique
  *	Correspond à zéro, un ou plusieurs caractères
  [abc]	Correspond à un seul caractère du jeu de caractères {a,b,c}.
  [a-z]	Correspond à un seul caractère de la plage de caractères {a…z}.
  [^a]	Correspond à un seul caractère qui ne fait pas partie du jeu ou de la plage de caractères {a}. Notez que le caractère ^ doit se trouver immédiatement à droite du crochet ouvrant.
  {ab,cd}	Correspond à une chaîne du jeu de chaînes {ab, cd}.
  {ab,c{de, fh}}	Correspond à une chaîne du jeu de chaînes {ab, cde, cfh}.

• FORMAT_OPTIONS

  Options à passer au lecteur de sources de données Apache Spark pour le format spécifié. Voir Options de format pour chaque format de fichier.

• COPY_OPTIONS

  Options permettant de contrôler le fonctionnement de la commande COPY INTO.

  • force : booléenne, par défaut false. Avec la valeur true, l'idempotence est désactivée et les fichiers sont chargés sans tenir compte du fait qu'ils ont déjà été chargés auparavant.
  • mergeSchema : booléenne, par défaut false. Avec la valeur true, le schéma peut évoluer en fonction des données entrantes.

Appeler COPY INTO simultanément

COPY INTO prend en charge les appels simultanés sur la même table. Tant qu’elle COPY INTO est appelée simultanément sur des ensembles distincts de fichiers d’entrée, chaque appel doit aboutir, sinon vous obtenez un conflit de transaction. COPY INTO ne doit pas être appelé simultanément pour améliorer les performances ; une commande unique COPY INTO avec plusieurs fichiers fonctionne généralement mieux que d’exécuter des commandes simultanées COPY INTO avec un seul fichier chacune. COPY INTO peut être appelé simultanément lorsque :

• Plusieurs producteurs de données n’ont pas un moyen facile de coordonner et ne peuvent pas effectuer un seul appel.
• Lorsqu’un répertoire très volumineux peut être ingéré sous-répertoire par sous-répertoire. Lors de l’ingestion de répertoires contenant un très grand nombre de fichiers, Databricks recommande d’utiliser Auto Loader lorsque cela est possible.

Accéder aux métadonnées des fichiers

Pour savoir comment accéder aux métadonnées pour les sources de données basées sur des fichiers, consultez la colonne Métadonnées de fichier.

Options de format

• Options génériques
• JSON options
• CSV options
• XML, options
• PARQUET options
• AVRO options
• BINARYFILE options
• TEXT options
• ORC options

Options génériques

Les options suivantes s’appliquent à tous les formats de fichier.

JSON options

CSV options

XML options

PARQUET options

AVRO options

BINARYFILE options

Les fichiers binaires n’ont pas d’autres options de configuration.

TEXT options

ORC options

Articles connexes

• Informations d'identification
• DELETE
• INSERT
• MERGE
• PARTITION
• query
• UPDATE
• Prise en main de COPY INTO pour charger des données.