Type de fichier et données non structurées

Important

Cette fonctionnalité est en version bêta. Les administrateurs d’espace de travail peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus . Consultez Gérer les préversions d’Azure Databricks.

Le FILE type stocke une référence gouvernée à un fichier non structuré, avec des métadonnées telles que le chemin et la taille. Utilisez FILE les colonnes dans le catalogue Unity pour stocker des documents, des images et de l’audio aux côtés des données structurées.

Avec les FILE MANAGED colonnes, Unity Catalog stocke des copies des fichiers et les gère avec la table : supprimer les lignes rend les fichiers référencés éligibles à la collecte des ordures, afin que la table et ses fichiers restent synchronisés.

Pour la référence typographique, voir FILE type.

Le schéma suivant montre une FILE colonne nommée video qui fait référence aux extraits de conduite aux côtés de colonnes structurées telles que l’itinéraire, la description de la scène et l’étiquette de danger :

Métadonnées et stockage du fichier

Pour chaque ligne, le FILE type stocke des métadonnées et un lien régi vers le fichier en stockage. Une valeur FILE inclut les champs de métadonnées uri, size, content_type et checksum. Les requêtes de métadonnées ne nécessitent pas de lectures complètes de fichiers, ce qui améliore la performance des requêtes.

Vous pouvez transmettre FILE des valeurs à des fonctions IA, telles que ai_parse_document la fonction, et aux fonctions définies par l’utilisateur (UDF).

Le diagramme suivant montre un exemple de colonne gérée FILE , contenant les métadonnées de chemin et de taille ainsi que des références aux fichiers en stockage :

Accès aux métadonnées et au contenu

Une valeur comporte deux parties, et l’accès FILE à chacune est régi différemment :

• Les métadonnées des fichiers (uri, size, content_type, et checksum) sont stockées dans les propres fichiers de données de la table. N’importe qui qui a SELECT sur la table peut le lire.
• Le contenu des fichiers reste en stockage. Pour les lire, il faut avoir accès au fichier : READ VOLUME sur le volume sous-jacent pour FILE EXTERNAL, ou avoir accès à la fois à la table et au volume sous-jacent au FileSpace pour FILE MANAGED.

Convertir une valeur FILE en BINARY ou STRING, la transmettre à une fonction d’IA ou à une UDF, et la prévisualiser dans le tableau des résultats entraînent tous la lecture du contenu des fichiers. Parce que les métadonnées font partie de la table, le chemin et la taille d’un fichier sont visibles pour quiconque peut interroger la table, même sans accès au contenu.

Pour prévisualiser les fichiers dans les résultats de requête, voir Aperçu des fichiers dans les colonnes FILE.

Pourquoi utiliser FILE au lieu de BINARY ou STRING

Le tableau suivant détaille les défis liés à la gestion de gros fichiers non structurés avec BINARY ou STRING types :

Type de colonne	Description	Diagramme
BINARY	Matérialise l’objet complet à chaque lecture, même si vous n’avez besoin que de métadonnées comme la taille ou le chemin du fichier. Cela entraîne des calculs inutiles et des requêtes lentes.
STRING	Stocke un chemin de fichier sans métadonnées, telles que la taille ou les informations de version, et sans lien régi entre la table et le fichier. Si une autre charge de travail supprime le fichier, la table contient des informations obsolètes. Si vous supprimez une ligne de tableau, le fichier référencé reste en stockage jusqu’à ce que vous le retiriez manuellement.

Sommes de contrôle

Le checksum champ est un jeton d’intégrité pour les octets du fichier, de la forme <prefix>:<digest>. Utilisez-le pour comparer des fichiers ou vérifier qu’un fichier n’a pas changé. Les lecteurs ignorent une somme de chèque avec un préfixe non reconnu.

Une somme de contrôle n’est pas toujours disponible. Lato_file fonction, create_file la fonction et copy_file la fonction renseignent la somme de contrôle lorsque le magasin d’objets retourne un ETAG. list_files fonction à valeurs de table et read_files fonction à valeurs de table ne renseignent pas la somme de contrôle.

Le checksum champ utilise l’un des préfixes suivants :

Préfixe	Encodage condensé	Description
ETAG	Opaque	L’eTag du magasin d’objets pour tout le fichier. Fourni à l’identique par la boutique, utilisé uniquement pour une comparaison d’égalité, et non recalculable.
MD5	Hexadécimal en minuscules	Un résumé MD5 (RFC 1321), 32 caractères hexadécimaux.
CRC32	Hexadécimal en minuscules	Une somme de contrôle CRC32 (RFC 2083), 8 caractères hexadécimaux.
CRC32C	Hexadécimal en minuscules	Une somme de contrôle CRC32C (RFC 3385), 8 caractères hexadécimaux.
SHA-256	Hexadécimal en minuscules	Un digest SHA-256 (RFC 6234), 64 caractères hexadécimaux.

Par exemple, une somme de contrôle MD5 ressemble à MD5:d41d8cd98f00b204e9800998ecf8427e, et un eTag d’un magasin d’objets ressemble à ETAG:"686897696a7c876b7e", y compris les guillemets doubles qui l’entourent et qui sont renvoyés par le magasin d’objets.

Sélectionnez entre FILE et BINARY

Le tableau suivant compare les options pour travailler avec des fichiers non structurés :

Type de colonne	Values	Cas d’utilisation
FILE	Une référence gouvernée à un fichier, plus les métadonnées (uri, size, content_type, checksum).	Utilisation pour gérer et traiter des fichiers non structurés en parallèle de données structurées, et pour passer des fichiers vers des fonctions intégrées et IA.
BINARY	Les octets bruts d’un fichier, en ligne dans une colonne.	Utilisez pour de petits objets (jusqu’à 64 Ko par défaut) stockés directement dans le fichier de données. C’est utile lorsque vous avez besoin d’une surcharge de métadonnées faible et d’une gestion simplifiée des fichiers. Par exemple, utilisez cette option pour stocker des vignettes directement dans les données de ligne.

FICHIER GÉRÉ et FICHIER EXTERNE

Le FILE type prend en compte deux approches pour gérer les fichiers :

• FILE MANAGED les colonnes copient les fichiers vers le stockage géré. Les permissions sont simplifiées et gérées dans le tableau. Lorsque vous supprimez des lignes ou les mettez à jour pour référencer différents fichiers, les fichiers non référencés deviennent éligibles à la collecte des ordures, de sorte que la table et ses fichiers restent synchronisés. Utilisez cette approche pour les charges de travail qui accèdent aux fichiers via une table, comme l’entraînement ML ou la génération augmentée par récupération (RAG), ainsi que pour les fichiers ingérés à partir de sources externes. Pour les modèles d’ingestion, voir Ingérer des fichiers en tant que type FILE.
• FILE EXTERNAL les colonnes font référence à des fichiers existants dans un volume du catalogue Unity. Les fichiers sont sécurisés grâce aux permissions de volume du catalogue Unity, mais leur cycle de vie n’est pas géré par le catalogue Unity, et ils ne sont pas copiés. Utilisez cette approche lorsque vous devez référencer des fichiers sans déplacer les données ni perturber les outils qui lisent depuis un volume existant.

Azure Databricks recommande FILE MANAGED pour les charges de travail bénéficiant des autorisations au niveau des fichiers et d’une conformité intégrée : l’accès à chaque fichier est géré par la table qui le référence, et supprimer des lignes rend les fichiers référencés éligibles à la collecte des ordures. À utiliser FILE EXTERNAL lorsque les fichiers doivent rester sur leurs chemins de volume existants pour les outils qui les lisent en dehors de la table.

Pour les requêtes, il n’y a aucune différence entre fichiers gérés et fichiers externes.

Le schéma suivant montre comment ce FILE type relie votre code aux fichiers dans le stockage d’objets cloud :

FILE MANAGED

FILE MANAGED les colonnes stockent des copies de fichiers dans un FileSpace, un volume du catalogue Unity que vous déclarez pour que la table l’utilise comme stockage géré. Leur cycle de vie est lié aux tables qui les font référence : supprimer les lignes rend les fichiers référencés éligibles à la collecte des ordures, afin que la table et ses fichiers restent synchronisés.

Les comportements suivants s’appliquent à FILE MANAGED:

• Déclarer le FileSpace nécessite la databricks.filespace-preview propriété de la table.
• La lecture ou l’écriture d’un fichier géré nécessite l’accès à la fois à la table et au volume sur lequel repose le FileSpace.
• La collecte automatique des fichiers non référencés n’est pas prise en charge en version Bêta.

Les fichiers non structurés stockés dans des sources externes telles que SharePoint, Google Drive, OneDrive et SFTP doivent être ingérés en tant que fichiers gérés avant de pouvoir les utiliser avec des fonctions telles que ai_parse_document les fonctions et les fonctions définies par l’utilisateur (UDF). Pour les modèles d’ingestion, voir Ingérer des fichiers en tant que type FILE.

Pour utiliser des fichiers gérés, créez une table avec une FILE MANAGED colonne et déclarez un volume comme le FileSpace en définissant la databricks.filespace-preview propriété de la table sur un chemin de volume :

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

Pour des exemples complets, voir les exemples suivants FILE MANAGED .

Exemples FILE MANAGED

Pour créer un tableau avec une FILE MANAGED colonne :

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

Pour ajouter une FILE MANAGED colonne à une table existante, définissez la databricks.filespace-preview propriété table avant d’ajouter la colonne, comme dans le code suivant :

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

Ajouter une colonne FILE MANAGED à une table qui n’a pas de FileSpace échoue.

Supprimer les fichiers gérés non référencés

Comme la collecte automatique des déchets n’est pas prise en charge, supprimez vous-même les fichiers non référencés. Le notebook suivant recherche les fichiers dans un FileSpace auxquels aucune version de table ne fait référence, et les supprime éventuellement :

Notebook de nettoyage de mémoire FileType

Obtenir un ordinateur portable

FILE EXTERNAL

FILE EXTERNAL les colonnes sont des références à des fichiers déjà existants dans un volume du catalogue Unity.

Si vous disposez des privilèges requis sur le volume, vous pouvez mettre à jour ou supprimer ces fichiers. Databricks recommande d’utiliser des fichiers immuables. Une attribution de table expose les métadonnées du fichier, mais la lecture des octets du fichier nécessite également le READ VOLUME privilège sur le volume sous-jacent.

Un fichier externe associe chaque ligne de table à un fichier situé sur son chemin existant dans un volume du catalogue Unity :

Exemples FILE EXTERNAL

Pour créer un tableau avec une FILE EXTERNAL colonne :

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

Pour ajouter une FILE EXTERNAL colonne à une table existante :

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

Pour créer et remplir une table à partir d’un volume, en attribuant des identifiants uniques à chaque fichier :

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

Gouvernance et comparaison du cycle de vie

Le tableau suivant compare comment FILE MANAGED et FILE EXTERNAL gouvernent l’accès aux fichiers ainsi que le cycle de vie des fichiers :

Type de colonne	FILE MANAGED	FILE EXTERNAL
Contrôle d’accès aux fichiers	Régis par les permissions de table et de volume, telles que SELECT sur la table et READ VOLUME sur le volume.	Régis par des permissions de volume, telles que READ VOLUME.
Cycle de vie et garbage collection	Les fichiers sont liés aux lignes qui les référencent. Supprimer ces lignes rend les fichiers éligibles à la collecte des ordures. La collecte automatique des déchets n’est pas prise en charge.	Vous gérez les dossiers vous-même. Supprimer une ligne de table n’affecte pas le fichier sous-jacent dans le volume.

Cas d’utilisation de type FICHIER

Les types gérés et externes FILE répondent tous deux aux défis suivants pour les cas d’utilisation utilisant des données non structurées :

Défi	Type supporté FILE	Benefits
Fichiers trop volumineux pour être stockés en ligne BINARY	FILE MANAGED ou FILE EXTERNAL	Une FILE colonne stocke une référence, donc un fichier n’est lu que lorsqu’une fonction IA ou une UDF le traite. Cela évite de matérialiser de gros objets directement dans la table.
Cycle de vie et gouvernance dissociés entre le système de fichiers et la table	FILE MANAGED	Azure Databricks associe le cycle de vie de chaque fichier à celui de la table, de sorte que la suppression de lignes rend les fichiers éligibles à la suppression au lieu de laisser des fichiers orphelins dans le stockage.
Charges de travail concurrentes qui nécessitent que les fichiers restent au même emplacement	FILE EXTERNAL	Les fichiers restent sur leurs chemins de volume existants, sans être affectés par le cycle de vie de la table, donc les autres outils qui lisent les mêmes fichiers ne sont pas perturbés.

Étapes suivantes

• Type FILE
• Importer des fichiers en tant que type FILE
• Tutoriel : Construis un pipeline de traitement de fichiers avec le type FICHIER
• ai_parse_document fonction