Colonne de métadonnées de fichier

Vous pouvez obtenir des informations de métadonnées pour les fichiers d’entrée avec la colonne _metadata. La colonne _metadata est une colonne masquée et est disponible pour tous les formats de fichier d’entrée. Pour inclure la _metadata colonne dans le DataFrame retourné, vous devez la sélectionner explicitement dans la requête de lecture où vous spécifiez la source.

Si la source de données contient une colonne nommée _metadata, les requêtes retournent la colonne depuis la source de données, plutôt que les métadonnées du fichier.

Avertissement

De nouveaux champs peuvent être ajoutés à la colonne _metadata dans les versions futures. Pour éviter des erreurs d’évolution du schéma si la colonne _metadata est mise à jour, Databricks recommande de sélectionner des champs spécifiques de la colonne dans vos requêtes. Consultez les exemples.

Métadonnées prises en charge

La colonne _metadata est un STRUCT contenant les champs suivants :

Nom	Type	Descriptif	Exemple	Version minimale de Databricks Runtime
file_path	`STRING`	Chemin d’accès du fichier d’entrée.	`file:/tmp/f0.csv`	10.5
file_name	`STRING`	Nom du fichier d’entrée avec son extension.	`f0.csv`	10.5
file_size	`LONG`	Longueur du fichier d’entrée, en octets.	628	10.5
file_modification_time	`TIMESTAMP`	Horodatage de la dernière modification du fichier d’entrée.	`2021-12-20 20:05:21`	10.5
file_block_start	`LONG`	Décalage de début du bloc en cours de lecture, en octets.	0	13.0
longueur_bloc_fichier	`LONG`	Longueur du bloc en cours de lecture, en octets.	628	13.0

Pour extraire des propriétés supplémentaires au niveau de l’objet cloud, consultez la colonne métadonnées de l’objet.

Exemples

Utilisation dans un lecteur basique de source de données basé sur des fichiers

Python

df = spark.read \
  .format("csv") \
  .schema(schema) \
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*") \
  .select("*", "_metadata")

display(df)

'''
Result:
+---------+-----+----------------------------------------------------+
|   name  | age |                 _metadata                          |
+=========+=====+====================================================+
|         |     | {                                                  |
|         |     |    "file_path": "/Volumes/catalog_name/            |
| Debbie  | 18  |      schema_name/volume_name/data/f0.csv",         |
|         |     |    "file_name": "f0.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-07-02 01:05:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
|         |     | {                                                  |
|         |     |    "file_path": "/Volumes/catalog_name/            |
| Frank   | 24  |      schema_name/volume_name/data/f1.csv",         |
|         |     |    "file_name": "f1.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-12-20 02:06:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
'''

Langage de programmation Scala

val df = spark.read
  .format("csv")
  .schema(schema)
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*")
  .select("*", "_metadata")

display(df)

/* Result:
+---------+-----+----------------------------------------------------+
|   name  | age |                 _metadata                          |
+=========+=====+====================================================+
|         |     | {                                                  |
|         |     |    "file_path": "/Volumes/catalog_name/            |
| Debbie  | 18  |      schema_name/volume_name/data/f0.csv",         |
|         |     |    "file_name": "f0.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-07-02 01:05:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
|         |     | {                                                  |
|         |     |    "file_path": "/Volumes/catalog_name/            |
| Frank   | 24  |      schema_name/volume_name/data/f1.csv",         |
|         |     |    "file_name": "f1.csv",                          |
|         |     |    "file_size": 10,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-12-20 02:06:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
*/

Sélectionner des champs spécifiques

Python

spark.read \
  .format("csv") \
  .schema(schema) \
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*") \
  .select("_metadata.file_name", "_metadata.file_size")

Langage de programmation Scala

spark.read
  .format("csv")
  .schema(schema)
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*")
  .select("_metadata.file_name", "_metadata.file_size")

Utiliser dans les filtres

Python

spark.read \
  .format("csv") \
  .schema(schema) \
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*") \
  .select("*") \
  .filter(col("_metadata.file_name") == lit("test.csv"))

Langage de programmation Scala

spark.read
  .format("csv")
  .schema(schema)
  .load("/Volumes/catalog_name/schema_name/volume_name/data/*")
  .select("*")
  .filter(col("_metadata.file_name") === lit("test.csv"))

Utiliser dans COPY INTO (hérité)

COPY INTO my_delta_table
FROM (
  SELECT *, _metadata FROM 'abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData'
)
FILEFORMAT = CSV

Utiliser dans Auto Loader

Si vos données sources contiennent une colonne nommée _metadata, renommez-la source_metadataen . Si vous ne le renommez pas, vous ne pouvez pas accéder à la colonne de métadonnées de fichier dans la table cible ; les requêtes retournent plutôt la colonne source.

Python

spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .schema(schema) \
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData") \
  .selectExpr("*", "_metadata as source_metadata") \
  .writeStream \
  .option("checkpointLocation", checkpointLocation) \
  .start(targetTable)

Langage de programmation Scala

spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .schema(schema)
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData")
  .selectExpr("*", "_metadata as source_metadata")
  .writeStream
  .option("checkpointLocation", checkpointLocation)
  .start(targetTable)

Si vous utilisez foreachBatch et souhaitez inclure la colonne de métadonnées de fichier dans le DataFrame de streaming, vous devez la référencer dans le DataFrame de lecture en continu avant la foreachBatch fonction. Si vous référencez uniquement la colonne de métadonnées de fichier à l’intérieur de la foreachBatch fonction, la colonne n’est pas incluse.

Python

spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData") \
  .select("*", "metadata") \
  .writeStream \
  .foreachBatch(...)

Langage de programmation Scala

spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData")
  .select("*", "metadata")
  .writeStream
  .foreachBatch(...)

Ressources supplémentaires

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-06-23