TVF read_files

S’applique à :oui coché Databricks SQL oui coché Databricks Runtime 13.3 LTS et versions ultérieures

Lit les fichiers sous un emplacement fourni et retourne les données sous forme tabulaire.

Prend en charge la lecture des formats de fichiers JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO et ORC. Peut détecter automatiquement le format de fichier et déduire un schéma unifié dans l’ensemble des fichiers.

Remarque

Disponible en version Bêta, configuré format => 'file' pour retourner une FILE référence pour chaque fichier au lieu de lire le contenu du fichier. Voir FILE les fichiers type et Ingest comme le type de fichier.

Syntaxe

read_files(path [, option_key => option_value ] [...])

Les arguments

Cette fonction nécessite un appel de paramètre nommé pour les clés d’option.

  • path : un STRING avec l’URI de l’emplacement des données. Prend en charge la lecture à partir de Azure Data Lake Storage ('abfss://'), de S3 (s3://) et de Google Cloud Storage ('gs://'). Peut contenir des globs. Consultez Découverte de fichiers pour plus de détails.
  • option_key : le nom de l’option à configurer. Vous devez utiliser des accents graves () for options that contain dots (.`).
  • option_value: expression constante sur laquelle définir l’option. Accepte les fonctions littérales et scalaires.

Retours

Table contenant les données des fichiers lus sous le fichier donné path. Le schéma dépend du format de fichier :

  • BINARYFILE: retourne un schéma fixe :

    Colonne Type Descriptif
    path STRING Chemin d’accès complet au fichier.
    modificationTime TIMESTAMP Heure de la dernière modification du fichier.
    length LONG Taille du fichier en octets.
    content BINARY Contenu binaire du fichier. Permet * EXCEPT (content) d’exclure le contenu binaire lors de l’interrogation des métadonnées de fichier.

  • TEXT: retourne un schéma fixe avec une seule value (STRING) colonne.

  • Tous les autres formats (JSON, CSV, XML, PARQUET, AVRO, ORC) : le schéma est déduit du contenu du fichier ou fourni explicitement à l’aide de l’option schema .

_metadata Colonne

read_files expose une _metadata colonne avec des métadonnées au niveau du fichier. Cette colonne n’est pas incluse dans les SELECT * résultats et doit être sélectionnée explicitement. Elle contient les champs suivants :

Champ Type Descriptif
file_path STRING Chemin complet du fichier source.
file_name STRING Nom du fichier source.
file_size LONG Taille du fichier source en octets.
file_modification_time TIMESTAMP Heure de la dernière modification du fichier source.
file_block_start LONG Début du bloc du fichier en cours de lecture.
file_block_length LONG Longueur du bloc du fichier en cours de lecture.

Pour inclure _metadata des résultats, sélectionnez-le explicitement :

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

Découverte de fichiers

read_files peut lire un fichier individuel ou lire des fichiers dans un répertoire fourni. read_files détecte tous les fichiers sous le répertoire fourni de manière récursive, sauf si un glob est fourni, ce qui indique à read_files d’effectuer une récurrence dans un modèle de répertoire spécifique.

Filtrage des répertoires ou des fichiers à l’aide de modèles Glob

Les modèles Glob peuvent être utilisés pour filtrer les répertoires et les fichiers lorsqu’ils sont fournis dans le chemin d’accès.

Modèle Descriptif
? 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 de l'ensemble 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}.

read_files utilise le globber strict d'Auto Loader lors de la découverte de fichiers avec globs. La configuration se fait avec l’option useStrictGlobber. Lorsque le globber strict est désactivé, les barres obliques de fin (/) sont supprimées et un modèle d’étoile tel que /*/ peut s’étendre à la découverte de plusieurs répertoires. Consultez les exemples ci-dessous pour voir la différence de comportement.

Modèle Chemins d'accès au fichier Globber strict désactivé Globber strict activé
/a/b /a/b/c/file.txt Oui Oui
/a/b /a/b_dir/c/file.txt Non Non
/a/b /a/b.txt Non Non
/a/b/ /a/b.txt Non Non
/a/*/c/ /a/b/c/file.txt Oui Oui
/a/*/c/ /a/b/c/d/file.txt Oui Oui
/a/*/d/ /a/b/c/d/file.txt Oui Non
/a/*/c/ /a/b/x/y/c/file.txt Oui Non
/a/*/c /a/b/c_file.txt Oui Non
/a/*/c/ /a/b/c_file.txt Oui Non
/a/*/c /a/b/cookie/file.txt Oui Non
/a/b* /a/b.txt Oui Oui
/a/b* /a/b/file.txt Oui Oui
/a/{0.txt,1.txt} /a/0.txt Oui Oui
/a/*/{0.txt,1.txt} /a/0.txt Non Non
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Oui Oui

Inférence de schéma

Le schéma des fichiers peut être fourni explicitement à read_files avec l’option schema. Lorsque le schéma n’est pas fourni, read_files tente de déduire un schéma unifié sur l’ensemble des fichiers découverts, ce qui nécessite la lecture de tous les fichiers, sauf si une instruction LIMIT est utilisée. Même lors de l’utilisation d’une requête LIMIT, un ensemble de fichiers plus grand que nécessaire peut être lu pour retourner un schéma plus représentatif des données. Databricks ajoute automatiquement une LIMIT instruction pour SELECT les requêtes dans les notebooks et l’éditeur SQL si un utilisateur n’en a pas fourni un.

L’option schemaHints peut être utilisée pour corriger des sous-ensembles du schéma déduit. Pour plus d’informations, consultez Remplacer l’inférence de schéma avec les indicateurs de schéma.

Un rescuedDataColumn est fourni par défaut pour sauver les données qui ne correspondent pas au schéma. Pour plus d’informations, consultez Qu’est-ce que la colonne de données récupérées ?. Vous pouvez supprimer le rescuedDataColumn en définissant l’option schemaEvolutionMode => 'none'.

Inférence de schéma de partition

read_files peut également déduire des colonnes de partitionnement si les fichiers sont stockés sous des répertoires partitionnés de style Hive, c’est-à-dire /column_name=column_value/. Si un schema est fourni, les colonnes de partition découvertes utilisent les types fournis dans le schema. Si les colonnes de partition ne font pas partie du schema fourni, les colonnes de partition déduites sont ignorées.

Si une colonne existe à la fois dans le schéma de partition et dans les colonnes de données, la valeur lue à partir de la valeur de partition est utilisée à la place de la valeur de données. Si vous souhaitez ignorer les valeurs provenant du répertoire et utiliser la colonne de données, vous pouvez fournir la liste des colonnes de partition dans une liste séparée par des virgules avec l’option partitionColumns.

L’option partitionColumns peut également être utilisée pour indiquer à read_files les colonnes découvertes à inclure dans le schéma déduit final. Le fait de fournir une chaîne vide ignore toutes les colonnes de partition.

L’option schemaHints peut également être fournie pour remplacer le schéma déduit pour une colonne de partition.

Les formats TEXT et BINARYFILE ont un schéma fixe, mais read_files tente également de déduire le partitionnement pour ces formats lorsque cela est possible.

Authentification pour le stockage cloud

read_files lit les fichiers à partir d’emplacements externes du catalogue Unity ou de volumes de catalogue Unity (gérés et externes). Vous devez disposer du READ FILES privilège sur l’emplacement externe ou le READ VOLUME privilège sur le volume qui contient les fichiers que vous souhaitez lire. Consultez Se connecter au stockage d’objets cloud à l’aide du catalogue Unity ou qu’est-ce que les volumes de catalogue Unity ?.

Utilisation dans les tables de diffusion en continu

read_files peut être utilisé dans des tables de flux pour ingérer des fichiers dans Delta Lake. read_files tire parti d’Auto Loader lorsqu’il est utilisé dans une requête de table en streaming. Vous devez utiliser le mot clé STREAM avec read_files. Pour plus d’informations, consultez Qu’est-ce qu’Auto Loader ?.

Lorsqu’il est utilisé dans une requête de diffusion en continu, read_files utilise un échantillon de données pour déduire le schéma et peut faire évoluer le schéma à mesure qu’il traite davantage de données. Pour plus d’informations, consultez Configurer l’inférence et l’évolution de schéma dans Auto Loader.

Paramètres

Options de base

Choix Type Descriptif Valeur par défaut
format String Format de fichier de données dans le chemin d’accès source. Inféré automatiquement s’il est omis. Les valeurs autorisées incluent , , , (Bêta), avro, binaryFile, csv, file, et json. orcparquettextxml None
schema String Schéma des fichiers à lire. Spécifiez une chaîne de schéma en utilisant le format DDL, par 'id int, ts timestamp, event string'exemple . Si elle est omise, read_files tente d’inférer un schéma unifié à travers les fichiers découverts. None
inferColumnTypes Boolean Indique s’il faut déduire les types de colonnes exacts lors de l’utilisation de l’inférence de schéma. Par défaut, les colonnes sont déduites lors de l’inférence de jeux de données JSON et CSV. C’est l’inverse du comportement par défaut de l’Auto Loader. Voir inférence de schéma. true
partitionColumns String Une liste séparée par virgules des colonnes de partition de style Ruche à déduire à partir de la structure des répertoires des fichiers. Les colonnes de partition de type ruche sont des paires clé-valeur combinées par un signe d’égalité, comme <base-path>/a=x/b=1/c=y/file.format. Dans cet exemple, les colonnes de partition sont a, b et c. Si vous utilisez l’inférence de schéma et que vous passez les <base-path> données pour charger les données, ces colonnes sont automatiquement ajoutées à votre schéma. Si vous spécifiez un schéma, le chargeur automatique s’attend à ce que ces colonnes soient incluses dans le schéma. Si vous ne voulez pas que ces colonnes fassent partie de votre schéma, spécifiez "" de les ignorer. Vous pouvez également utiliser cette option pour déduire des colonnes à partir du chemin du fichier dans des structures de répertoires complexes. Par exemple, pour les fichiers suivants, en spécifiant cloudFiles.partitionColumns comme year,month,day retours year=2022 pour file1.csv, mais les month colonnes et day sont null. month et day sont correctement analysés pour file2.csv et file3.csv:
<base-path>/year=2022/week=1/file1.csv
<base-path>/year=2022/month=2/day=3/file2.csv
<base-path>/year=2022/month=2/day=4/file3.csv		 None
schemaHints String Informations de schéma que vous transmettez à Auto Loader lors de l’inférence de schéma. Pour plus d’informations, consultez les conseils de schéma. None
useStrictGlobber Boolean Indique s’il faut utiliser un globber strict correspondant au comportement de globbing par défaut d’autres sources de fichiers dans Apache Spark. Pour plus d’informations, consultez Modèles de chargement de données courants. Disponible dans Databricks Runtime 12.2 LTS et versions ultérieures. C’est l’inverse du mode par défaut pour Auto Loader. true

Options spécifiques au format

Pour obtenir des options spécifiques à chaque format de fichier (JSON, CSV, XML, Parquet, Avro, text, ORC et binary), consultez les options DataFrameReader.

Options de diffusion en continu

Ces options s’appliquent lors de l’utilisation de read_files à l’intérieur d’une table de diffusion en continu ou d’une requête de diffusion en continu.

Choix Type Descriptif Valeur par défaut
allowOverwrites Boolean S’il faut retraiter les fichiers qui changent après la découverte. Lors d’un rafraîchissement, read_files il retraite un fichier s’il a été modifié après le dernier rafraîchissement réussi. false
includeExistingFiles Boolean Indique si les fichiers existants doivent être inclus dans le chemin d’entrée du traitement du flux ou si seuls les nouveaux fichiers arrivant après la configuration initiale doivent être traités. Cette option est évaluée uniquement lorsque vous démarrez un flux pour la première fois. La modification de cette option après le redémarrage du flux n’a aucun effet. true
maxBytesPerTrigger Byte String Le nombre maximal de nouveaux octets à traiter dans chaque déclencheur. Vous pouvez spécifier une chaîne d’octets comme 10g pour limiter chaque microlot à 10 Go de données. Il s’agit d’une valeur maximale non stricte. Si vous avez des fichiers de 3 Go chacun, Azure Databricks traite 12 Go dans un microbatch. Lorsqu’elle est utilisée avec maxFilesPerTrigger, Azure Databricks consomme jusqu’à la limite inférieure de maxFilesPerTrigger ou maxBytesPerTrigger, selon la première atteinte. Pour les tables de streaming créées sur des entrepôts SQL serverless, ne définissez pas cette option ni maxFilesPerTrigger, pour exploiter le contrôle d’admission dynamique. None
maxFilesPerTrigger Integer Le nombre maximal de nouveaux fichiers à traiter à chaque déclencheur. Lorsqu’elle est utilisée avec maxBytesPerTrigger, Azure Databricks consomme jusqu’à la limite inférieure de maxFilesPerTrigger ou maxBytesPerTrigger, selon la première atteinte. Pour les tables de streaming créées sur des entrepôts SQL serverless, ne définissez pas cette option ni maxBytesPerTrigger, pour exploiter le contrôle d’admission dynamique. 1000
schemaEvolutionMode String Mode d’évolution du schéma à mesure que de nouvelles colonnes sont découvertes dans les données. Par défaut, les colonnes sont déduites sous forme de chaînes lors de l’inférence de jeux de données JSON. Pour plus d’informations, consultez Évolution de schéma. Cette option ne s’applique pas aux fichiers text et binaryFile. "addNewColumns" sans schéma, "none" sinon.
schemaLocation String Emplacement dans lequel stocker le schéma inféré et les modifications ultérieures. Pour plus d’informations, consultez Inférence de schéma. L’emplacement du schéma n’est pas nécessaire lorsqu’il est utilisé dans une requête de table de streaming. None

Exemples

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');

-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv')

-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')

-- Reads a single JSON file
> SELECT * FROM read_files(
    'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')

-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'json',
    schemaHints => 'id int')

-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
    'gs://my-bucket/avroData',
    modifiedAfter => date_sub(current_date(), 1),
    modifiedBefore => current_date())

-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
  AS SELECT *, _metadata.file_path
  FROM read_files('gs://my-bucket/avroData')

-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
  AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);

Utiliser des fichiers non structurés

Les exemples suivants utilisent BINARYFILE le format pour lire et filtrer des fichiers non structurés stockés dans des volumes de catalogue Unity, et combiner read_files avec des fonctions IA pour traiter le contenu des fichiers.

Répertoriez tous les fichiers d’un volume : utilisez * EXCEPT (content) pour renvoyer les métadonnées de fichier sans charger de contenu binaire, puis sélectionnez _metadata explicitement pour inclure des champs de métadonnées au niveau du fichier.

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

Répertorier les fichiers image filtrés par taille : permet fileNamePattern de cibler des types de fichiers image spécifiques et de filtrer pour _metadata.file_size retourner uniquement les fichiers dans une plage de tailles donnée.

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;

Répertorier les fichiers PDF modifiés au cours du dernier jour : utilisez fileNamePattern pour cibler les fichiers PDF et filtrer pour modificationTime renvoyer uniquement les fichiers modifiés au cours du dernier jour.

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;

Exécutez une fonction IA sur des fichiers image : permet ai_query de traiter les fichiers image lus à partir d’un chemin de stockage cloud. Filtrez sur les _metadata champs pour cibler des fichiers spécifiques.

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(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Analyser des documents correspondant à un modèle de nom de fichier : permet ai_parse_document d’extraire du contenu structuré à partir de fichiers PDF et d’images. Filtrez par _metadata.file_name pour cibler des fichiers spécifiques.

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 => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';

Joindre des fichiers avec une table structurée : les workflows non structurés nécessitent souvent la fusion de données structurées stockées dans des tables avec des fichiers non structurés. L’exemple suivant joint des fichiers dans un chemin de stockage cloud avec deux tables structurées, en filtrant par taille de fichier et par attribut utilisateur. La jointure avec user_files est effectuée en extrayant l’ID de fichier à partir du chemin d’accès du fichier à l’aide split et element_at.

SELECT
  users.user_id,
  user_files.file_id,
  files._metadata.file_name AS file_name,
  files.* EXCEPT (content),
  ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
  's3://my-bucket-name/files/',
  format => 'binaryFile',
  fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
  ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
  ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
  AND files._metadata.file_size < 10000000;
  • Last updated on