Colonne de métadonnées d’objet

Important

Cette fonctionnalité est disponible en préversion publique.

La _object_metadata colonne est une colonne de métadonnées masquée qui expose les propriétés au niveau de l’objet cloud pour chaque fichier lu par une source de données basée sur un fichier. Contrairement _metadata à (qui contient des informations telles que le chemin d’accès de fichier, la taille et le temps de modification), _object_metadata fournit des propriétés de couche de stockage plus riches extraites via des API cloud, notamment le type MIME, les métadonnées clé-valeur définies par l’utilisateur, les métadonnées définies par le système et les balises d’objet.

La _object_metadata colonne nécessite Databricks Runtime 18.2 ou supérieur et est disponible pour tous les formats de fichiers d’entrée lors de la lecture depuis le stockage d’objets dans le cloud. Pour inclure la _object_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 _object_metadata, les requêtes 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 d’objet cloud dans ce cas, ajoutez un trait de soulignement 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 d’accès ou la taille du fichier peuvent être interrogées à l’aide de la _metadata colonne. Pour plus d’informations sur la _metadata colonne, consultez la colonne de métadonnées de fichier.

Avertissement

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

Schema

La _object_metadata colonne contient STRUCT les champs suivants, disponibles à partir de Databricks Runtime 18.2. Tous les champs sont nullables.

Nom	Catégorie	Description	Example
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 modifications ou le contrôle de version.	"abc123def456"
user_metadata	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éfinis par l’utilisateur. Consultez les en-têtes de métadonnées définis par l’utilisateur dans la documentation AWS. Dans Azure Blob, il s’agit de métadonnées définies par l’utilisateur. Consultez Manage blob properties and metadata with .NET dans la documentation Azure.	{"my_key":"my_value"}
system_metadata	VARIANT	Des paires clé-valeur définies par le système par le fournisseur de stockage cloud.	{"Content-Length":"1024", ...}
balises	VARIANT	Paires clé-valeur de balise d’objet définies par l’utilisateur stockées sur l’objet. Par exemple, dans S3, il s’agit de balises d’objet. Consultez catégoriser vos objets à l’aide de balises dans la documentation AWS. Tous les services de stockage cloud ne prennent pas en charge les balises d’objet. Consultez les notes relatives au comportement par fournisseur.	{"my_tag":"my_value"}

Exemples

Les exemples suivants montrent comment lire et interroger la colonne _object_metadata à l’aide de différentes méthodes d’ingestion.

Lire un lot de fichiers

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

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

Diffuser des fichiers avec le chargeur automatique

L’exemple suivant utilise le chargeur automatique pour diffuser en continu des fichiers à partir du stockage cloud et écrire la _object_metadata colonne dans une table Delta.

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 de schéma dues à de futures modifications de _object_metadata, sélectionnez uniquement les champs précis dont vous avez besoin.

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 lors de la sélection de la _object_metadata colonne.

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 cast. Vous pouvez extraire des valeurs spécifiques à l’aide de l’opérateur de transtypage :: ou des fonctions VARIANT. Consultez VARIANT type.

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>`

Remarques

Gardez à l’esprit ce qui suit lors de l’utilisation _object_metadata.

• La colonne _object_metadata fonctionne avec Amazon S3, Azure DFS, Azure Blob et GCP.
• La sélection d’un champ dans _object_metadata déclenche jusqu’à deux appels supplémentaires à l’API du cloud par fichier, de sorte que les requêtes portant sur un grand nombre de petits fichiers peuvent subir une certaine augmentation de la latence.
• _object_metadata.tags est pris en charge pour S3 et Stockage Blob Azure (non-HNS, blob.core.windows.net). Sur tous les autres fournisseurs (Azure DFS, WASB, GCP), tags retourne {}.
• Pour S3, les informations d’identification doivent disposer de l’autorisation s3:GetObjectTagging. S’il n’est pas disponible, tags retourne null.
• Si Databricks rencontre une erreur lors de l’extraction des balises à partir d’un fournisseur pris en charge, tags retourne null.
• Les métadonnées système, les métadonnées utilisateur et les balises ne sont pas disponibles pour le stockage géré par Databricks et sont définies sur null.