Objektmetadatenspalte

Important

Dieses Feature befindet sich in der Betaversion. Arbeitsbereichsadministratoren können den Zugriff auf dieses Feature über die Vorschauseite steuern. Siehe Manage Azure Databricks Previews.

Die _object_metadata Spalte ist eine ausgeblendete Metadatenspalte, die Eigenschaften auf Cloudobjektebene für jede Datei verfügbar macht, die von einer dateibasierten Datenquelle gelesen wird. Im Gegensatz zu _metadata (die Informationen wie Dateipfad, Größe und Änderungszeit enthalten) _object_metadata bietet umfassendere Speicherebeneneigenschaften, die über Cloud-APIs abgerufen werden , einschließlich MIME-Typ, ETag, benutzerdefinierte Schlüsselwertmetadaten, systemdefinierte Metadaten und Objekttags.

Die _object_metadata Spalte ist für alle Eingabedateiformate beim Lesen aus dem Cloudobjektspeicher verfügbar. Um die _object_metadata Spalte in den zurückgegebenen DataFrame einzuschließen, müssen Sie sie explizit in der Leseabfrage auswählen, in der Sie die Quelle angeben.

Wenn die Datenquelle eine Spalte mit dem Namen _object_metadataenthält, werden Abfragen für _object_metadata die Datenquelle zurückgegeben, nicht die Metadaten des Cloudobjekts. Um in diesem Fall auf die Metadatenspalte des Cloudobjekts zuzugreifen, stellen Sie einen zusätzlichen Unterstrich (__object_metadata) voran. Wiederholen Sie diesen Vorgang, wenn __object_metadata auch kollidiert.

Allgemeine Dateimetadaten wie der Dateipfad oder die Größe können mithilfe der _metadata Spalte abgefragt werden. Weitere Informationen zur Spalte finden Sie in der _metadataSpalte "Dateimetadaten".

Warning

Neue Felder können der Spalte _object_metadata in zukünftigen Releases hinzugefügt werden. Um Schemaentwicklungsfehler zu verhindern, wenn die _object_metadata Spalte aktualisiert wird, können Sie bestimmte Felder aus der Spalte in Ihren Abfragen auswählen. Siehe Beispiele.

Schema

Die _object_metadata Spalte enthält STRUCT die folgenden Felder, die ab Databricks Runtime 18.1 verfügbar sind. Alle Felder können null sein.

Name	Typ	Description	Example
mime_type	STRING	MIME-Typ (Inhaltstyp) des Objekts, zum Beispiel application/parquet oder text/csv.	application/parquet
etag	STRING	ETag des Objekts. ETags sind nützlich zum Erkennen von Änderungen oder zur Versionierung.	"abc123def456"
user_metadata	VARIANT	Benutzerdefinierte Metadatenschlüssel-Wert-Paare, die im Objekt gespeichert sind. In S3 sind dies beispielsweise benutzerdefinierte Metadatenheader. Siehe benutzerdefinierte Metadatenheader in der AWS-Dokumentation . In Azure Blob sind dies benutzerdefinierte Metadaten. Weitere Informationen finden Sie unter Manage blob properties and metadata with .NET in the Azure documentation.	{"my_key":"my_value"}
system_metadata	VARIANT	Vom Cloudspeicheranbieter festgelegte systemdefinierte Schlüssel-Wert-Paare.	{"Content-Length":"1024", ...}
Tags	VARIANT	Benutzerdefinierte Objekttag-Schlüsselwertpaare, die im Objekt gespeichert sind. In S3 sind dies beispielsweise Objekttags. Weitere Informationen finden Sie unter Kategorisieren Ihrer Objekte mithilfe von Tags in der AWS-Dokumentation. Nicht alle Cloudspeicherdienste unterstützen Objekttags. Siehe Hinweise zum Verhalten pro Anbieter.	{"my_tag":"my_value"}

Beispiele

Die folgenden Beispiele zeigen, wie Sie die _object_metadata-Spalte mithilfe verschiedener Erfassungsmethoden lesen und abfragen.

Lesen eines Batches von Dateien

Im folgenden Beispiel wird eine CSV-Datei gelesen und es werden sowohl die Spalten _metadata als auch _object_metadata ausgewählt.

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

Streamen von Dateien mit automatischem Ladeprogramm

Im folgenden Beispiel wird auto Loader verwendet, um Dateien aus dem Cloudspeicher zu streamen und die _object_metadata Spalte in eine Delta-Tabelle zu schreiben.

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)

Auswählen bestimmter Felder

Um Schemaentwicklungsfehler aus zukünftigen Änderungen zu _object_metadatavermeiden, wählen Sie nur die spezifischen Felder aus, die Sie benötigen.

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

Mit COPY INTO verwenden

Im folgenden Beispiel wird COPY INTO verwendet, um Dateien in eine Delta-Tabelle zu laden, wobei die Spalte _object_metadata ausgewählt wird.

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

Extrahieren von Werten aus VARIANT Feldern

Die Felder user_metadata, system_metadata und tags sind vom Typ VARIANT. Im folgenden Beispiel werden bestimmte Werte mithilfe des :: Umwandlungsoperators extrahiert. Sie können bestimmte Werte mithilfe des ::Typumwandlungsoperators oder der VARIANTFunktionen extrahieren. Siehe VARIANT Typ.

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

Hinweise

Beachten Sie bei der Verwendung _object_metadatafolgendes.

• Die Spalte _object_metadata funktioniert mit Amazon S3, Azure DFS, Azure Blob und GCP.
• Wenn Sie ein beliebiges Feld aus _object_metadata Triggern auswählen, werden bis zu zwei zusätzliche Cloud-API-Aufrufe pro Datei ausgelöst, sodass Abfragen über eine große Anzahl kleiner Dateien möglicherweise zu einer Latenzsteigerung führen.
• _object_metadata.tags wird für S3 und Azure Blob Storage (nicht HNS, blob.core.windows.net) unterstützt. Bei allen anderen Anbietern (Azure DFS, WASB, GCP) gibt tags{} zurück.
• Für S3 müssen die Anmeldedaten die Berechtigung s3:GetObjectTagging haben. Falls nicht verfügbar, gibt tagsnull zurück.
• Wenn beim Abrufen von Tags von einem unterstützten Anbieter durch Databricks ein Fehler auftritt, gibt tagsnull zurück.
• Systemmetadaten, Benutzermetadaten und Tags sind für den Databricks-verwalteten Speicher nicht verfügbar und auf null festgelegt.