Colonne de métadonnées d'objet

info

Aperçu

Cette fonctionnalité est en aperçu public.

La colonne _object_metadata est une colonne de métadonnées masquée qui expose les propriétés au niveau des objets cloud pour chaque fichier lu par une source de données basée sur des fichiers. Contrairement à _metadata (qui contient des informations comme le chemin du fichier, la taille et l'heure de modification), _object_metadata offre des propriétés de couche de stockage plus riches, récupérées via les APIs cloud — y compris le type MIME, l'ETag, les métadonnées clé-valeur définies par l'utilisateur, les métadonnées définies par le système et les tags d'objets.

La colonne _object_metadata est disponible pour tous les formats de fichiers d'entrée lors de la lecture à partir du stockage d'objets cloud. Pour inclure la colonne _object_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 _object_metadata, les requêtes effectuées sur _object_metadata renvoient la colonne de la source de données, et non les métadonnées de l'objet cloud. Pour accéder à la colonne de métadonnées de l'objet cloud dans ce cas, prépendez un underscore supplémentaire (__object_metadata). Répétez si __object_metadata entre également en collision.

Les métadonnées de fichier courantes, telles que le chemin du fichier ou la taille, peuvent être interrogées à l'aide de la colonne _metadata. Pour plus d'informations sur la colonne _metadata, consultez la colonne de métadonnées de fichier.

attention

De nouveaux champs pourraient être ajoutés à la colonne _object_metadata dans les futures versions. Pour éviter les erreurs d'évolution des schémas si la colonne _object_metadata est mise à jour, vous pouvez sélectionner des champs spécifiques de la colonne dans vos query. Voir Exemples.

Schéma

La colonne _object_metadata est un(e) STRUCT contenant les champs suivants, disponible à partir de Databricks Runtime 18.1. Tous les champs peuvent être nuls.

Nom	Type	Description	Exemple
mime_type	`STRING`	Type MIME (type de contenu) de l'objet, par exemple `application/parquet` ou `text/csv`.	`application/parquet`
etag	`STRING`	ETag de l'objet. Les ETags sont utiles pour détecter les changements ou le versioning.	`"abc123def456"`
métadonnées utilisateur	`VARIANT`	Paires clé-valeur de métadonnées définies par l'utilisateur stockées sur l'objet. Par exemple, dans S3, il s'agit d'en-têtes de métadonnées définies par l'utilisateur. Consultez En-têtes de métadonnées définies par l'utilisateur dans la documentation AWS. Dans Azure Blob, il s'agit de métadonnées définies par l'utilisateur. Consultez Gérer les propriétés et les métadonnées des blobs avec .NET dans la documentation Azure.	`{"my_key":"my_value"}`
system_metadata	`VARIANT`	Paires clé-valeur définies par le système et définies par le fournisseur de stockage cloud.	`{"Content-Length":"1024", ...}`
Tags	`VARIANT`	Paires clé-valeur de tag d'objet définies par l'utilisateur, stockées sur l'objet. Par exemple, dans S3, ce sont des tags d'objets. Consultez Categorizing your objects using tags dans la documentation AWS. Tous les services de stockage cloud ne prennent pas en charge les tags d'objets. Consultez Remarques pour le comportement par fournisseur.	`{"my_tag":"my_value"}`

Nom	Type	Description	Exemple
mime_type	`STRING`	Type MIME (type de contenu) de l'objet, par exemple `application/parquet` ou `text/csv`.	`application/parquet`
etag	`STRING`	ETag de l'objet. Les ETags sont utiles pour détecter les changements ou le versioning.	`"abc123def456"`
métadonnées utilisateur	`VARIANT`	Paires clé-valeur de métadonnées définies par l'utilisateur stockées sur l'objet. Par exemple, dans S3, il s'agit d'en-têtes de métadonnées définies par l'utilisateur. Consultez En-têtes de métadonnées définies par l'utilisateur dans la documentation AWS. Dans Azure Blob, il s'agit de métadonnées définies par l'utilisateur. Consultez Gérer les propriétés et les métadonnées des blobs avec .NET dans la documentation Azure.	`{"my_key":"my_value"}`
system_metadata	`VARIANT`	Paires clé-valeur définies par le système et définies par le fournisseur de stockage cloud.	`{"Content-Length":"1024", ...}`
Tags	`VARIANT`	Paires clé-valeur de tag d'objet définies par l'utilisateur, stockées sur l'objet. Par exemple, dans S3, ce sont des tags d'objets. Consultez Categorizing your objects using tags dans la documentation AWS. Tous les services de stockage cloud ne prennent pas en charge les tags d'objets. Consultez Remarques pour le comportement par fournisseur.	`{"my_tag":"my_value"}`

Exemples

Les exemples suivants montrent comment lire et query la colonne _object_metadata en utilisant différentes méthodes d'ingestion.

Lire un batch de fichiers

L'exemple suivant lit un fichier CSV et sélectionne les colonnes _metadata et _object_metadata.

Python
Scala

Python
path = "<path-to-load-from>"

df = spark.read.format("csv").load(path)
display(df.select("*", "_metadata", "_object_metadata"))

Scala
val path = "<path-to-load-from>"

val df = spark.read.format("csv").load(path)
display(df.select("*", "_metadata", "_object_metadata"))

Stream files with Auto Loader

L’exemple suivant utilise Auto Loader pour Stream des fichiers depuis le cloud et écrit la colonne _object_metadata dans une table Delta.

Python
Scala

Python
path = "<path-to-load-from>"
checkpoint = "<checkpoint-path>"
schema_location = "<schema-location-path>"
table = "<output-table-path>"

dsw = (spark.readStream
    .format("cloudFiles")
    .option("cloudFiles.format", "text")
    .option("cloudFiles.schemaLocation", schema_location)
    .option("header", "true")
    .load(path)
    .selectExpr("*", "_metadata as md", "_object_metadata as obj_md")
    .writeStream
    .format("delta")
    .option("checkpointLocation", checkpoint)
    .trigger(once=True)
    .start(table)
)

dsw.awaitTermination()

df = spark.read.format("delta").load(table).select("value", "md", "obj_md")
display(df)

Scala
val path = "<path-to-load-from>"
val checkpoint = "<checkpoint-path>"
val schemaLocation = "<schema-location-path>"
val table = "<output-table-path>"

val dsw = spark.readStream
    .format("cloudFiles")
    .option("cloudFiles.format", "text")
    .option("cloudFiles.schemaLocation", schemaLocation)
    .option("header", "true")
    .load(path)
    .selectExpr("*", "_metadata as md", "_object_metadata as obj_md")
    .writeStream
    .format("delta")
    .option("checkpointLocation", checkpoint)
    .trigger(Trigger.Once)
    .start(table)

dsw.awaitTermination()

val df = spark.read.format("delta").load(table).select("value", "md", "obj_md")
display(df)

Sélectionner des champs spécifiques

Pour éviter les erreurs d'évolution des schémas dues à de futures modifications de _object_metadata, sélectionnez uniquement les champs spécifiques dont vous avez besoin.

Python
Scala

Python
path = "<path-to-load-from>"

(spark.read
   .format("csv")
   .schema(schema)
   .load(path)
   .select("_object_metadata.user_metadata", "_object_metadata.tags", "_object_metadata.etag"))

Scala
val path = "<path-to-load-from>"

spark.read
  .format("csv")
  .schema(schema)
  .load(path)
  .select("_object_metadata.user_metadata", "_object_metadata.tags", "_object_metadata.etag")

Utiliser avec `COPY INTO`

L’exemple suivant utilise COPY INTO pour charger des fichiers dans une table Delta tout en sélectionnant la colonne _object_metadata.

SQL
COPY INTO my_delta_table
FROM (
  SELECT *, _object_metadata FROM '<path-to-load-from>'
)
FILEFORMAT = CSV

Extraire des valeurs de `VARIANT` champs

Les champs user_metadata, system_metadata et tags sont de type VARIANT. L'exemple suivant extrait des valeurs spécifiques à l'aide de l'opérateur de transtypage ::. Vous pouvez extraire des valeurs spécifiques à l'aide de l'opérateur de transtypage :: ou des fonctions VARIANT. Voir le VARIANT type.

Python
SQL

Python
path = "<path-to-load-from>"

(spark.read
   .format("csv")
   .schema(schema)
   .load(path)
   .selectExpr(
     "*",
     "_object_metadata.user_metadata:my_key::string as my_key",
     "_object_metadata.tags:environment::string as env_tag"
   ))

SQL
SELECT
  *,
  _object_metadata.user_metadata:my_key::STRING AS my_key,
  _object_metadata.tags:environment::STRING AS env_tag
FROM csv.`<path-to-load-from>`

Notes

Gardez ce qui suit à l'esprit lorsque vous utilisez _object_metadata.

La colonne _object_metadata fonctionne avec Amazon S3, Azure DFS, Azure Blob et GCP.
La sélection d'un champ quelconque de _object_metadata déclenche jusqu'à deux appels API cloud supplémentaires par fichier, ainsi, les requêtes sur un grand nombre de petits fichiers peuvent subir une augmentation de la latence.
_object_metadata.tags est pris en charge pour S3 et Azure Blob Storage (non-HNS, blob.core.windows.net). Sur tous les autres fournisseurs (Azure DFS, WASB, GCP), tags retourne {}.
Pour S3, l'identifiant doit avoir l'autorisation s3:GetObjectTagging. Si non disponible, tags renvoie null.
Si Databricks rencontre une erreur lors de la récupération des tags d'un fournisseur pris en charge, tags renvoie null.
Les métadonnées système, les métadonnées utilisateur et les tags ne sont pas disponibles pour le stockage géré par Databricks et sont définis sur null.

Schéma​

Exemples​

Lire un batch de fichiers​

Stream files with Auto Loader​

Sélectionner des champs spécifiques​

Utiliser avec COPY INTO​

Extraire des valeurs de VARIANT champs​

Notes​