Type de FILE et données non structurées

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs de Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Aperçus . Voir Gérer les prévisualisations Databricks.

Le type FILE stocke une référence régie vers un fichier non structuré, avec des métadonnées telles que le chemin et la taille. Utilisez les colonnes FILE dans Unity Catalog pour stocker des documents, des images et des fichiers audio parallèlement aux données structurées.

Avec FILE MANAGED colonnes, Unity Catalog stocke des copies des fichiers et les gère avec la table : la suppression de lignes rend les fichiers référencés éligibles au garbage collection, afin que la table et ses fichiers restent synchronisés.

Pour la référence de type, consultez typeFILE.

Le diagramme suivant montre une colonne FILE nommée video qui référence des clips 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 de FILE

Pour chaque ligne, le type FILE stocke des métadonnées et un Link gouverné vers le fichier dans le 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 lecture complète des fichiers, ce qui améliore les performances des requêtes.

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

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

Pourquoi utiliser FILE au lieu de BINARY ou STRING

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

Type de colonne	Description	Diagramme
BINARY	Matérialise l’objet complet pour chaque lecture, même lorsque vous n’avez besoin que de métadonnées telles que la taille ou le chemin d’accès du fichier. Cela entraîne des calculs inutiles et des query lentes.
STRING	Stocke un chemin de fichier sans métadonnées, telles que des informations de taille ou de version, et sans Link gouverné 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 table, le fichier référencé reste dans le stockage jusqu'à ce que vous le supprimiez manuellement.

Type de colonne	Description	Diagramme
BINARY	Matérialise l’objet complet pour chaque lecture, même lorsque vous n’avez besoin que de métadonnées telles que la taille ou le chemin d’accès du fichier. Cela entraîne des calculs inutiles et des query lentes.
STRING	Stocke un chemin de fichier sans métadonnées, telles que des informations de taille ou de version, et sans Link gouverné 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 table, le fichier référencé reste dans le stockage jusqu'à ce que vous le supprimiez manuellement.

Sommes de contrôle

Le champ checksum 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 été modifié. Les lecteurs ignorent une somme de contrôle avec un préfixe non reconnu.

Une somme de contrôle n'est pas toujours disponible. Fonctionto_file, fonctioncreate_file et fonctioncopy_file renseignent la somme de contrôle lorsque le stockage d'objets renvoie un ETAG. Fonction à valeur tabulairelist_files et fonction à valeur tabulaireread_files ne renseignent pas la somme de contrôle.

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

Préfixe	Encodage de condensat	Description
ETAG	Opaque	L’eTag du stockage d’objets pour l’intégralité du fichier. Fourni tel quel par le stockage, utilisé uniquement pour la comparaison d’égalité et non recalculable.
MD5	Hex en minuscules	Une empreinte MD5 (RFC 1321), 32 caractères hexadécimaux.
CRC32	Hex en minuscules	Une somme de contrôle CRC32 (RFC 2083), 8 caractères hexadécimaux.
CRC32C	Hex en minuscules	Une somme de contrôle CRC32C (RFC 3385), 8 caractères hexadécimaux.
SHA-256	Hex en minuscules	Une empreinte SHA-256 (RFC 6234), 64 caractères hexadécimaux.

Préfixe	Encodage de condensat	Description
ETAG	Opaque	L’eTag du stockage d’objets pour l’intégralité du fichier. Fourni tel quel par le stockage, utilisé uniquement pour la comparaison d’égalité et non recalculable.
MD5	Hex en minuscules	Une empreinte MD5 (RFC 1321), 32 caractères hexadécimaux.
CRC32	Hex en minuscules	Une somme de contrôle CRC32 (RFC 2083), 8 caractères hexadécimaux.
CRC32C	Hex en minuscules	Une somme de contrôle CRC32C (RFC 3385), 8 caractères hexadécimaux.
SHA-256	Hex en minuscules	Une empreinte SHA-256 (RFC 6234), 64 caractères hexadécimaux.

Par exemple, une somme de contrôle MD5 ressemble à MD5:d41d8cd98f00b204e9800998ecf8427e, et un eTag de stockage d'objets ressemble à ETAG:"686897696a7c876b7e", en incluant les guillemets doubles environnants renvoyés par le stockage d'objets.

Sélectionnez entre FILE et BINARY

Le tableau suivant compare les options de travail avec des fichiers non structurés :

Type de colonne	Valeurs	Cas d'usage
FILE	Une référence gouvernée vers un fichier, ainsi que des métadonnées (uri, size, content_type, checksum).	À utiliser pour gérer et traiter des fichiers non structurés parallèlement à des données structurées, et pour transmettre des fichiers à des fonctions intégrées et IA.
BINARY	Les octets bruts d’un fichier, intégrés dans une colonne.	À utiliser pour les petits objets (jusqu'à 64 Ko default) stockés directement dans le fichier de données. Ceci est utile lorsque vous avez besoin d'une faible surcharge de métadonnées et d'une gestion de fichiers simplifiée. Par exemple, utilisez ceci pour stocker des vignettes en ligne avec les données de ligne.

Type de colonne	Valeurs	Cas d'usage
FILE	Une référence gouvernée vers un fichier, ainsi que des métadonnées (uri, size, content_type, checksum).	À utiliser pour gérer et traiter des fichiers non structurés parallèlement à des données structurées, et pour transmettre des fichiers à des fonctions intégrées et IA.
BINARY	Les octets bruts d’un fichier, intégrés dans une colonne.	À utiliser pour les petits objets (jusqu'à 64 Ko default) stockés directement dans le fichier de données. Ceci est utile lorsque vous avez besoin d'une faible surcharge de métadonnées et d'une gestion de fichiers simplifiée. Par exemple, utilisez ceci pour stocker des vignettes en ligne avec les données de ligne.

FILE MANAGED et FILE EXTERNAL

Le type FILE prend en charge deux approches pour la gestion des fichiers :

• FILE MANAGED les colonnes copient les fichiers vers le stockage géré. Les autorisations sont simplifiées et gérées via la table. Lorsque vous supprimez des lignes ou que vous les mettez à jour pour référencer des fichiers différents, les fichiers non référencés deviennent éligibles au garbage collection, afin que la table et ses fichiers restent synchronisés. Utilisez cette approche pour les workloads qui accèdent aux fichiers via une table, tels que l’entraînement ML ou la génération augmentée de récupération (RAG), et pour les fichiers ingérés à partir de sources externes. Pour les modèles d’ingestion, consultez Ingérer des fichiers en tant que type FILE.
• FILE EXTERNAL les colonnes référencent des fichiers existants dans un volume Unity Catalog. Les fichiers sont sécurisés par les autorisations de volume Unity Catalog, mais leur cycle de vie n'est pas géré par Unity Catalog et ils ne sont pas copiés. Utilisez cette approche lorsque vous devez référencer des fichiers sans déplacer de données ni perturber les outils qui lisent à partir d'un volume existant.

Databricks recommande FILE MANAGED pour les workloads qui bénéficient d’autorisations au niveau du fichier et d’une conformité intégrée : l’accès à chaque fichier est régi par la table qui le référence, et la suppression de lignes rend les fichiers référencés éligibles au garbage collection. Utilisez FILE EXTERNAL lorsque les fichiers doivent rester à 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 les fichiers gérés et les fichiers externes.

Le diagramme suivant montre comment le type FILE connecte 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 Unity Catalog que vous déclarez pour que la table l’utilise comme stockage géré. Leur cycle de vie est lié aux tables qui les référencent : la suppression de lignes rend les fichiers référencés éligibles au nettoyage de la mémoire, afin que la table et ses fichiers restent synchronisés.

Les comportements suivants s’appliquent à FILE MANAGED:

• La déclaration de FileSpace nécessite la propriété de table databricks.filespace-preview.
• La lecture ou l'écriture d'un fichier géré nécessite un accès à la fois à la table et au volume qui prend en charge le FileSpace.
• La récupération automatique de mémoire 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 que vous puissiez les utiliser avec des fonctions telles que la fonctionai_parse_document et les fonctions définies par l’utilisateur (UDF). Pour les modèles d’ingestion, consultez Ingérer des fichiers en tant que type FILE.

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

Text

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

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

FILE MANAGED exemples

Pour créer une table avec une colonne FILE MANAGED :

SQL

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

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

SQL

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

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

L’ajout d’une colonne FILE MANAGED à une table qui ne contient aucun FileSpace échoue.

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

La récupération de mémoire automatique n'étant pas prise en charge, supprimez vous-même les fichiers non référencés. Le notebook suivant recherche les fichiers dans un FileSpace qu'aucune version de table ne référence, et les supprime éventuellement :

Notebook de récupération de mémoire FileType

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

FILE EXTERNAL

FILE EXTERNAL les colonnes sont des références à des fichiers qui existent déjà dans un volume Unity Catalog.

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

Un fichier externe mappe chaque ligne de table à un fichier situé à son chemin d’accès existant dans un volume Unity Catalog :

FILE EXTERNAL exemples

Pour créer une table avec une colonne FILE EXTERNAL :

SQL

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

Pour ajouter une colonne FILE EXTERNAL à une table existante :

SQL

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

Pour créer et renseigner une table à partir d'un volume, en attribuant des ID uniques à chaque fichier :

SQL

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

Comparaison de la gouvernance et du cycle de vie

Le tableau suivant compare la manière dont FILE MANAGED et FILE EXTERNAL régissent l’accès aux fichiers et gèrent le cycle de vie des fichiers :

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

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

Cas d’utilisation du type de fichier

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

Défi	Type FILE pris en charge	Avantages
Fichiers trop volumineux pour être stockés en ligne sous forme de BINARY	FILE MANAGED OU FILE EXTERNAL	Une colonne FILE stocke une référence, de sorte qu’un fichier n’est lu que lorsqu’une fonction IA ou une UDF le traite. Cela évite de matérialiser de gros objets en ligne dans la table.
Cycle de vie et gouvernance déconnectés entre le système de fichiers et la table	FILE MANAGED	Databricks lie le cycle de vie de chaque fichier à la table ; ainsi, la suppression de lignes rend les fichiers éligibles au nettoyage au lieu de laisser des fichiers orphelins dans le stockage.
Workloads simultanés qui nécessitent que les fichiers restent au même emplacement	FILE EXTERNAL	Les fichiers restent à leurs chemins de volume existants, sans être affectés par le cycle de vie de la table, afin que les autres outils qui lisent les mêmes fichiers ne soient pas perturbés.

Défi	Type FILE pris en charge	Avantages
Fichiers trop volumineux pour être stockés en ligne sous forme de BINARY	FILE MANAGED OU FILE EXTERNAL	Une colonne FILE stocke une référence, de sorte qu’un fichier n’est lu que lorsqu’une fonction IA ou une UDF le traite. Cela évite de matérialiser de gros objets en ligne dans la table.
Cycle de vie et gouvernance déconnectés entre le système de fichiers et la table	FILE MANAGED	Databricks lie le cycle de vie de chaque fichier à la table ; ainsi, la suppression de lignes rend les fichiers éligibles au nettoyage au lieu de laisser des fichiers orphelins dans le stockage.
Workloads simultanés qui nécessitent que les fichiers restent au même emplacement	FILE EXTERNAL	Les fichiers restent à leurs chemins de volume existants, sans être affectés par le cycle de vie de la table, afin que les autres outils qui lisent les mêmes fichiers ne soient pas perturbés.

Étapes suivantes

• FILE Type
• Ingérer les fichiers en tant que type FILE
• Tutoriel : créer un pipeline de traitement de fichiers avec le type FILE
• ai_parse_document fonction