Aller au contenu principal
Dernière mise à jour le

Travaillez avec les fichiers dans les volumes Unity Catalog

Cette page contient des exemples de gestion des fichiers dans les volumes Unity Catalog pour diverses interfaces utilisateur, outils, bibliothèques et langages.

Databricks recommande d'utiliser des volumes pour gérer tous les accès aux données non tabulaires dans le stockage d'objets cloud et pour stocker les fichiers de support de charge de travail. Voici quelques exemples :

  • Fichiers de données pour l'ingestion, tels que CSV, JSON et Parquet
  • Fichiers texte, image et audio pour les charges de travail de Data Science, de ML et d'IA.
  • Artéfacts CSV ou JSON écrits par Databricks pour l’intégration avec des systèmes externes
  • Bibliothèques, scripts d'initialisation et artefacts de build

Les volumes fournissent des chemins de type Portable Operating System Interface (POSIX) qui fonctionnent avec des outils et des frameworks dépendants de Filesystem in Userspace (FUSE). Cela les rend idéaux pour les frameworks de Machine Learning et les modules Python open source qui nécessitent un accès de type POSIX. Pour des informations détaillées sur les schémas URI, les chemins POSIX et leur relation avec les volumes, consultez Dois-je fournir un schéma URI pour accéder aux données ?.

Méthodes de gestion des fichiers dans les volumes​

Pour des exemples rapides de chaque méthode, consultez Travailler avec des fichiers dans les volumes Unity Catalog.

Interface

Description

Interface utilisateur de Catalog Explorer

Gestion interactive des fichiers via le workspace Databricks

Accès programmatique

Lisez et écrivez des fichiers à l'aide d'Apache Spark, Pandas ou SQL

services Databricks

Opérations de fichier utilisant dbutils.fs ou des commandes magiques (%fs, %sh) dans les Notebooks

Lister et query des fichiers

query file metadata using READ_FILES and filter by properties.

Commandes SQL

Opérations de fichiers à l'aide de mots-clés SQL (LIST, PUT INTO, GET, REMOVE) et connecteurs

Databricks CLI

Opérations en ligne de commande à l'aide de commandes databricks fs

SDK

Opérations sur les fichiers à l'aide des SDK Python, Java ou Go.

API REST

Accès direct à l’API pour les intégrations personnalisées

Interface

Description

Interface utilisateur de Catalog Explorer

Gestion interactive des fichiers via le workspace Databricks

Accès programmatique

Lisez et écrivez des fichiers à l'aide d'Apache Spark, Pandas ou SQL

services Databricks

Opérations de fichier utilisant dbutils.fs ou des commandes magiques (%fs, %sh) dans les Notebooks

Lister et query des fichiers

query file metadata using READ_FILES and filter by properties.

Commandes SQL

Opérations de fichiers à l'aide de mots-clés SQL (LIST, PUT INTO, GET, REMOVE) et connecteurs

Databricks CLI

Opérations en ligne de commande à l'aide de commandes databricks fs

SDK

Opérations sur les fichiers à l'aide des SDK Python, Java ou Go.

API REST

Accès direct à l’API pour les intégrations personnalisées

Utilisez l'Explorateur de catalogue​

Catalog Explorer propose des options pour les tâches courantes de gestion de fichiers pour les fichiers stockés avec les volumes Unity Catalog.

Pour interagir avec des fichiers dans un volume, procédez comme suit :

  1. Dans votre workspace Databricks, cliquez sur Icône de données. Catalogue .
  2. Recherchez ou parcourez le volume avec lequel vous souhaitez travailler et sélectionnez-le.

Pour plus de détails sur la création et la gestion des volumes, consultez Créer et gérer les volumes Unity Catalog.

upload files to a volume​

Vous pouvez upload des fichiers de tout format — structurés, semi-structurés ou non structurés — vers un volume. Les volumes prennent en charge des fichiers jusqu’à la taille maximale prise en charge par le stockage cloud sous-jacent. Toutefois, lorsque vous upload des fichiers vers un volume via l'interface utilisateur Databricks, une limite de taille de fichier de 5 Go est appliquée. Pour upload des fichiers de plus de 5 Go, utilisez le SDK Databricks pour Python. Pour plus de détails, voir Gérer les fichiers dans les volumes Unity Catalog.

Exigences​

Avant d'upload vers un volume, assurez-vous d'avoir les éléments suivants :

  • Un Workspace avec Unity Catalog activé
  • WRITE VOLUME sur le volume cible
  • USE SCHEMA sur le schéma parent
  • USE CATALOG sur le catalogue parent

Pour plus de détails, consultez les références des privilèges Unity Catalog.

Étapes d'upload​

  1. Dans la barre latérale, cliquez sur Nouveau , puis sur Ajouter ou upload des données .
  2. Cliquez sur upload les fichiers vers un volume .
  3. Sous Fichiers , cliquez sur Parcourir ou glissez-déposez des fichiers dans la zone de dépôt.
  4. Sous Volume de destination , sélectionnez un volume ou un répertoire, ou collez un chemin de volume.

Si aucun volume n’existe dans le schéma cible, vous pouvez en créer un en cliquant sur Créer un volume . Dans le volume, vous pouvez créer un nouveau répertoire.

remarque

Pour upload vos propres fichiers sans créer au préalable un catalogue, un schéma et un volume, vous pouvez sélectionner Mes fichiers, un volume par utilisateur, comme destination. Mes fichiers est en bêta. Consultez Stocker les fichiers dans Mes fichiers.

upload d’un fichier vers un volume à l’aide de l’interface utilisateur

Vous pouvez également accéder à l'UI d'upload des manières suivantes :

  • Dans l'Explorateur de catalogue : Ajouter des données > upload les fichiers vers un volume
  • Depuis un Notebook : **Fichier** > **upload les fichiers vers le volume**

Étapes suivantes​

Après avoir upload vers un volume, vous pouvez faire ce qui suit :

download files from a volume​

Pour download des fichiers à partir d'un volume, procédez comme suit :

  1. Sélectionnez un ou plusieurs fichiers.
  2. Cliquez sur download pour télécharger ces fichiers.

Supprimer les fichiers d'un volume​

Pour supprimer des fichiers d'un volume, procédez comme suit :

  1. Sélectionnez un ou plusieurs fichiers.
  2. Cliquez sur **Supprimer**.
  3. Cliquez sur **Supprimer** pour confirmer dans la boîte de dialogue qui s'affiche.

Créer un répertoire vide​

Pour créer un nouveau répertoire dans un volume, veuillez procéder comme suit :

  1. Sur l'onglet de présentation du volume, cliquez sur **Créer un répertoire**.
  2. Entrez un nom de répertoire.
  3. Cliquez sur Créer .

download un répertoire​

Pour download un répertoire dans un volume, procédez comme suit :

  1. Cliquez sur le menu kebab Icône du menu kebab. à droite du répertoire.
  2. Cliquez sur Download le répertoire .

Le répertoire est téléchargé au format ZIP.

Supprimer des répertoires d'un volume​

Pour supprimer des répertoires d’un volume, procédez comme suit :

  1. Sélectionnez un ou plusieurs répertoires.
  2. Cliquez sur **Supprimer**.
  3. Cliquez sur **Supprimer** pour confirmer dans la boîte de dialogue qui s'affiche.

Tâches de gestion de fichiers de l'interface utilisateur pour les volumes​

Cliquez sur le menu kebab Icône du menu kebab. à côté d'un nom de fichier pour effectuer les actions suivantes :

  • Copier le chemin
  • download le fichier
  • Supprimer le fichier
  • Créer une table

Créer une table à partir des données d'un volume​

Databricks fournit une interface utilisateur pour créer une table gérée par Unity Catalog à partir d'un fichier, de fichiers ou d'un répertoire de fichiers stockés dans un volume Unity Catalog.

Vous devez disposer des autorisations CREATE TABLE dans le schéma cible et avoir accès à un SQL Warehouse en cours d'exécution.

  1. Sélectionnez un ou plusieurs fichiers ou un répertoire. Les fichiers doivent avoir le même Layout de données.

  2. Cliquez sur Créer une table . La boîte de dialogue Créer une table à partir des volumes s'affiche.

  3. Utilisez la boîte de dialogue fournie pour examiner un aperçu des données et compléter les configurations suivantes :

    • Choisissez de Créer une nouvelle table ou de Remplacer la table existante
    • Sélectionnez le catalogue et le schéma cibles.
    • Spécifiez le Nom de la table .
    • (Facultatif) Outrepassez les noms et types de colonnes default, ou choisissez d'exclure des colonnes.
remarque

Cliquez sur Attributs avancés pour afficher les options supplémentaires.

  1. Cliquez sur Créer une table pour créer la table avec les attributs spécifiés. Une fois l'opération terminée, l'Explorateur de catalogue affiche les détails de la table.

Travailler par programme avec des fichiers dans des volumes​

Lisez et écrivez des fichiers dans des volumes à partir de toutes les langues prises en charge et des éditeurs Workspace en utilisant le format suivant :

/Volumes/catalog_name/schema_name/volume_name/path/to/files

Vous interagissez avec les fichiers dans les volumes de la même manière que vous interagissez avec les fichiers dans n'importe quel emplacement de stockage d'objets cloud. Cela signifie que si vous gérez actuellement du code qui utilise des URI cloud, des chemins de montage DBFS ou des chemins racine DBFS pour interagir avec des données ou des fichiers, vous pouvez mettre à jour votre code pour utiliser des volumes à la place.

remarque

Les volumes sont uniquement utilisés pour les données non tabulaires. Databricks recommande d'enregistrer les données tabulaires à l'aide des tables Unity Catalog, puis de lire et d'écrire des données à l'aide des noms de table.

Lecture et écriture des données dans les volumes​

Utilisez Apache Spark, Pandas, Spark SQL et d'autres bibliothèques OSS pour lire et écrire des fichiers de données en volumes.

Les exemples suivants illustrent la lecture d'un fichier CSV stocké dans un volume :

Python
df = spark.read.format("csv").load("/Volumes/catalog_name/schema_name/volume_name/data.csv")

display(df)

Commandes utilitaires pour les fichiers dans les volumes​

Databricks fournit les outils suivants pour la gestion des fichiers dans les volumes :

Pour un exemple d'utilisation de ces outils pour download des fichiers depuis Internet, décompresser des fichiers et déplacer des fichiers du stockage de blocs éphémères vers des volumes, consultez Download des données depuis Internet.

Vous pouvez également utiliser des packages OSS pour les commandes d'utilitaires de fichier, tels que le module Python os, comme illustré dans l’exemple suivant :

Python
import os

os.mkdir('/Volumes/catalog_name/schema_name/volume_name/directory_name')

Points de contrôle DataFrame dans les volumes​

Vous pouvez utiliser les chemins de volume Unity Catalog pour stocker les points de contrôle des DataFrame. Les points de contrôle des DataFrame tronquent le plan d'exécution d'un DataFrame et sauvegardent le contenu dans le stockage. Cela peut améliorer les performances pour les algorithmes itératifs et les plans de query complexes en évitant des lignées excessivement longues lors de la réutilisation des DataFrames.

Le stockage des points de contrôle dans les volumes Unity Catalog applique la gouvernance et les contrôles d'accès à vos données de point de contrôle, vous aidant ainsi à vous éloigner des chemins de stockage cloud non gérés.

Exigences​

  • Databricks Runtime 18.1 ou une version ultérieure.
  • Compute compatible Unity Catalog avec mode d'accès dédié ou standard. Les points de contrôle DataFrame dans les volumes ne sont pas pris en charge sur le compute Serverless.

Configurez le répertoire des points de contrôle​

La méthode de définition du répertoire de point de contrôle dépend du mode d'accès de votre compute :

Sur le compute avec mode d'accès dédié, utilisez SparkContext.setCheckpointDir:

Python
spark.checkpoint.dir=/Volumes/<catalog>/<schema>/<volume>/checkpoint

Créer un point de contrôle DataFrame​

Après avoir configuré le répertoire de point de contrôle, utilisez DataFrame.checkpoint() pour tronquer le plan d'exécution et enregistrer les données :

Python
df = spark.range(100).withColumn("doubled", col("id") * 2)
checkpointed_df = df.checkpoint()
remarque

Les points de contrôle DataFrame diffèrent des points de contrôle Structured Streaming. Pour plus d'informations sur le stockage des données de point de contrôle de streaming dans des volumes, consultez les points de contrôle Structured Streaming.

Lister et interroger les fichiers dans les volumes avec SQL​

Vous pouvez utiliser la fonction SQL read_files à valeur de table pour lister les fichiers dans un volume et interroger leurs métadonnées. Ceci est utile pour découvrir des fichiers, filtrer par propriétés de fichier et préparer des fichiers pour le traitement avec des fonctions d'IA.

Lors de l'utilisation de READ_FILES avec format => "binaryFile", la fonction renvoie une table avec les colonnes suivantes :

  • path: Le chemin d'accès complet au fichier
  • modificationTime: Le dernier timestamp de modification
  • length: La taille du fichier en octets
  • content: le contenu brut du fichier en tant que données binaires

Vous pouvez également sélectionner la colonne _metadata pour accéder à des informations de fichier supplémentaires, notamment file_path, file_name, file_size et file_modification_time.

Lister tous les fichiers dans un volume​

L’exemple suivant répertorie tous les fichiers d’un volume, à l’exception du contenu binaire :

SQL
SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  "/Volumes/<catalog>/<schema>/<volume>",
  format => "binaryFile"
);

Filtrer les fichiers par type et par taille​

L'exemple suivant filtre les fichiers image entre 20 Ko et 1 Mo :

SQL
SELECT * EXCEPT (content), _metadata
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{jpg,jpeg,png,JPG,JPEG,PNG}"
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

Filtrer les fichiers par heure de modification​

L’exemple suivant trouve les fichiers PDF modifiés au cours du dernier jour :

SQL
SELECT * EXCEPT (content), _metadata
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{pdf,PDF}"
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

Traiter les images avec les fonctions IA​

L'exemple suivant utilise la fonction ai_query pour générer des descriptions pour des fichiers image :

SQL
SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{jpg,jpeg,png}"
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Analyser des documents avec des fonctions d'IA​

L'exemple suivant utilise la fonction ai_parse_document pour extraire des données structurées des reçus PDF :

SQL
SELECT
  path AS file_path,
  ai_parse_document(content, map('version', '2.0')) AS result
FROM read_files(
  "/Volumes/main/public/my_files/",
  format => "binaryFile",
  fileNamePattern => "*.{pdf,PDF}"
)
WHERE _metadata.file_name ILIKE '%receipt%';

Gérer les fichiers dans les volumes à partir d'outils externes​

Databricks fournit une suite d'outils pour la gestion programmatique de fichiers dans des volumes depuis votre environnement local ou des systèmes intégrés.

Commandes SQL pour les fichiers dans les volumes​

Databricks prend en charge les mots-clés SQL suivants pour interagir avec les fichiers dans les volumes :

Dans les Notebooks Databricks et l'éditeur de requêtes SQL, seule la commande LIST est prise en charge. Les autres commandes SQL (PUT INTO, GET et REMOVE) sont disponibles via les connecteurs et les drivers Databricks SQL suivants, qui prennent en charge la gestion des fichiers dans les volumes :

Gérer les fichiers dans des volumes avec le Databricks CLI​

Utilisez les sous-commandes dans databricks fs. Voir fs groupe de commandes.

remarque

Le CLI Databricks exige que le schéma dbfs:/ précède tous les chemins de volumes. Par exemple, dbfs:/Volumes/catalog_name/schema_name/volume_name/path/to/data.

Gérer les fichiers dans les volumes avec les SDK​

Les SDK suivants prennent en charge la gestion des fichiers dans les volumes :

Gérer les fichiers dans les volumes avec l’API REST​

Utilisez l'API Fichiers pour gérer les fichiers dans les volumes.

Exemples d'API REST pour les fichiers dans les volumes​

Les exemples suivants utilisent curl et l'API REST Databricks pour effectuer des tâches de gestion de fichiers dans les volumes.

L'exemple suivant crée un dossier vide nommé my-folder dans le volume spécifié.

Bash
curl --request PUT "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

L'exemple suivant crée un fichier nommé data.csv avec les données spécifiées dans le chemin spécifié du volume.

Bash
curl --request PUT "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv?overwrite=true" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/octet-stream" \
--data-binary $'id,Text\n1,Hello World!'

L'exemple suivant répertorie le contenu d'un volume dans le chemin spécifié. Cet exemple utilise jq pour formater le JSON du corps de la réponse afin d’en faciliter la lecture.

Bash
curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

L’exemple suivant répertorie le contenu d’un dossier dans un volume du chemin d’accès spécifié. Cet exemple utilise jq pour formater le JSON du corps de la réponse afin d’en faciliter la lecture.

Bash
curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

L'exemple suivant affiche le contenu d'un fichier dans le chemin d'accès spécifié d'un volume.

Bash
curl --request GET "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

L'exemple suivant supprime un fichier dans le chemin d'accès spécifié d'un volume.

Bash
curl --request DELETE "https://${DATABRICKS_HOST}/api/2.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

L'exemple suivant supprime un dossier du volume spécifié.

Bash
curl --request DELETE "https://${DATABRICKS_HOST}/api/2.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Limitations du travail avec les fichiers dans les volumes​

Avant de travailler avec des fichiers dans des volumes, tenez compte des limitations suivantes :

  • Les ajouts directs ou les écritures non séquentielles (aléatoires) ne sont pas pris en charge. Ceci affecte les opérations telles que l'écriture de fichiers Zip et Excel. Pour ces charges de travail :

    1. Effectuer les opérations sur un disque local en premier.
    2. Copiez les résultats vers le volume.

    Par exemple :

    Python
    # python
    import xlsxwriter
    from shutil import copyfile

    workbook = xlsxwriter.Workbook('/local_disk0/tmp/excel.xlsx')
    worksheet = workbook.add_worksheet()
    worksheet.write(0, 0, "Key")
    worksheet.write(0, 1, "Value")
    workbook.close()

    copyfile('/local_disk0/tmp/excel.xlsx', '/Volumes/my_catalog/my_schema/my_volume/excel.xlsx')

  • Les fichiers éparses ne sont pas pris en charge. Pour copier des fichiers éparses, utilisez cp --sparse=never:

    Bash
    $ cp sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file
    error writing '/dbfs/sparse.file': Operation not supported
    $ cp --sparse=never sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file
Sur cette page