Kolom met objectmetagegevens

De _object_metadata kolom is een verborgen kolom met metagegevens die eigenschappen op cloudobjectniveau beschikbaar maakt voor elk bestand dat wordt gelezen door een gegevensbron op basis van een bestand. In tegenstelling tot _metadata (die informatie zoals bestandspad, grootte en wijzigingstijd bevat), _object_metadata biedt uitgebreidere eigenschappen voor opslaglagen die worden opgehaald via cloud-API's, waaronder MIME-type, ETag, door de gebruiker gedefinieerde sleutelwaardemetagegevens, door het systeem gedefinieerde metagegevens en objecttags.

De _object_metadata kolom vereist Databricks Runtime 18.2 of hoger en is beschikbaar voor alle invoerbestandsformaten wanneer je leest vanuit cloudobjectopslag. Als u de _object_metadata kolom in het geretourneerde DataFrame wilt opnemen, moet u deze expliciet selecteren in de leesquery waarin u de bron opgeeft.

Als de gegevensbron een kolom met de naam _object_metadata bevat, retourneren query's op _object_metadata de kolom uit de gegevensbron, niet de metagegevens van het cloudobject. Als u in dit geval toegang wilt krijgen tot de kolom metagegevens van het cloudobject, moet u een extra onderstrepingsteken (__object_metadata) toepassen. Herhaal dit als __object_metadata ook conflicteert.

Algemene bestandsmetagegevens, zoals het bestandspad of de grootte, kunnen worden opgevraagd met behulp van de _metadata kolom. Zie _metadata voor meer informatie over de kolom.

Schema

De _object_metadata kolom bevat STRUCT de volgende velden, beschikbaar vanaf Databricks Runtime 18.2. Alle velden zijn null-baar.

Examples

In de volgende voorbeelden ziet u hoe u de _object_metadata kolom kunt lezen en er query's op kunt uitvoeren met behulp van verschillende opnamemethoden.

Een reeks bestanden lezen

In het volgende voorbeeld wordt een CSV-bestand gelezen en worden zowel de kolommen _metadata als _object_metadata geselecteerd.

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

Bestanden streamen met Auto Loader

In het volgende voorbeeld wordt Auto Loader gebruikt om bestanden vanuit cloudopslag te streamen en de _object_metadata kolom naar een Delta-tabel te schrijven.

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)

Specifieke velden selecteren

Om fouten door schema-evolutie als gevolg van toekomstige wijzigingen in _object_metadata te voorkomen, selecteert u alleen de velden die u nodig hebt.

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

Te gebruiken met COPY INTO

In het volgende voorbeeld wordt COPY INTO gebruikt om bestanden in een Delta-tabel te laden, waarbij de kolom _object_metadata wordt geselecteerd.

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

Waarden extraheren uit VARIANT velden

De user_metadatavelden , system_metadataen tags velden zijn VARIANT type. In het volgende voorbeeld worden specifieke waarden geëxtraheerd met behulp van de :: cast-operator. U kunt specifieke waarden extraheren met behulp van de :: cast-operator of VARIANT -functies. Zie 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>`

Opmerkingen

Houd rekening met het volgende bij het gebruik van _object_metadata.

• De kolom _object_metadata werkt met Amazon S3, Azure DFS, Azure Blob en GCP.
• Het selecteren van een willekeurig veld uit _object_metadata activeert maximaal twee extra cloud-API-aanroepen per bestand, dus query’s over een groot aantal kleine bestanden kunnen enige extra latentie ondervinden.
• _object_metadata.tags wordt ondersteund voor S3 en Azure Blob Storage (niet-HNS, blob.core.windows.net). Op alle andere providers (Azure DFS, WASB, GCP) retourneert tags{}.
• Voor S3 moeten de inloggegevens over de machtiging s3:GetObjectTagging beschikken. Als deze niet beschikbaar is, retourneert tagsnull.
• Als Databricks een fout tegenkomt bij het ophalen van tags van een ondersteunde provider, retourneert tagsnull.
• Systeemmetagegevens, gebruikersmetagegevens en tags zijn niet beschikbaar voor door Databricks beheerde opslag en zijn ingesteld op null.