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 colonne _metadata dans le DataFrame renvoyé, vous devez la sélectionner explicitement dans la query de lecture où vous spécifiez la source.

Si la source de données contient une colonne nommée _metadata, les query renvoient la colonne de la source de données, et non les métadonnées du fichier.

attention

De nouveaux champs pourraient être ajoutés à la colonne _metadata dans les futures versions. Pour éviter les erreurs d’évolution des schémas si la colonne _metadata est mise à jour, Databricks recommande de sélectionner des champs spécifiques de la colonne dans vos queries. Voir des exemples.

Métadonnées prises en charge

La colonne _metadata est un STRUCT contenant les champs suivants :

Nom	Type	Description	Exemple	Version minimale de Databricks Runtime
file_path	`STRING`	Chemin d'accès au 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
taille_fichier	`LONG`	Longueur du fichier d'entrée, en octets.	628	10,5
file_modification_time	`TIMESTAMP`	Timestamp 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 start du bloc en cours de lecture, en octets.	0	13,0
longueur_de_bloc_de_fichier	`LONG`	Longueur du bloc en cours de lecture, en octets.	628	13,0

Nom	Type	Description	Exemple	Version minimale de Databricks Runtime
file_path	`STRING`	Chemin d'accès au 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
taille_fichier	`LONG`	Longueur du fichier d'entrée, en octets.	628	10,5
file_modification_time	`TIMESTAMP`	Timestamp 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 start du bloc en cours de lecture, en octets.	0	13,0
longueur_de_bloc_de_fichier	`LONG`	Longueur du bloc en cours de lecture, en octets.	628	13,0

Pour récupérer des propriétés supplémentaires au niveau de l'objet cloud, consultez colonne de métadonnées d'objet.

Exemples

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

Python
Scala

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" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
'''

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
Scala

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

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
Scala

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"))

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"))

Utilisation dans COPY INTO (hérité)

SQL
COPY INTO my_delta_table
FROM (
  SELECT *, _metadata FROM 's3://my-bucket/csvData'
)
FILEFORMAT = CSV

Utiliser dans Auto Loader

Si vos données sources contiennent une colonne nommée _metadata, renommez-la en source_metadata. Si vous ne la renommez pas, vous ne pouvez pas accéder à la colonne de métadonnées du fichier dans la table cible ; les query renvoient la colonne source à la place.

Python
Scala

Python
spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .schema(schema) \
  .load("s3://my-bucket/csvData") \
  .selectExpr("*", "_metadata as source_metadata") \
  .writeStream \
  .option("checkpointLocation", checkpointLocation) \
  .start(targetTable)

Scala
spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .schema(schema)
  .load("s3://my-bucket/csvData")
  .selectExpr("*", "_metadata as source_metadata")
  .writeStream
  .option("checkpointLocation", checkpointLocation)
  .start(targetTable)

Si vous utilisez foreachBatch et que vous 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 de streaming avant la fonction foreachBatch. Si vous ne référencez que la colonne de métadonnées de fichier à l'intérieur de la fonction foreachBatch, la colonne n'est pas incluse.

Python
Scala

Python
spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .load("s3://my-bucket/csvData") \
  .select("*", "metadata") \
  .writeStream \
  .foreachBatch(...)

Scala
spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .load("s3://my-bucket/csvData")
  .select("*", "metadata")
  .writeStream
  .foreachBatch(...)

Métadonnées prises en charge​

Exemples​

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

Sélectionner des champs spécifiques​

Utiliser dans les filtres​

Utilisation dans COPY INTO (hérité)​

Utiliser dans Auto Loader​

Ressources supplémentaires​