Objektmetadatakolumn

Important

Den här funktionen finns som allmänt tillgänglig förhandsversion.

Kolumnen _object_metadata är en dold metadatakolumn som exponerar egenskaper på molnobjektnivå för varje fil som läss av en filbaserad datakälla. Till skillnad från _metadata (som innehåller information som filsökväg, storlek och ändringstid) _object_metadata ger bättre egenskaper för lagringslager som hämtats via moln-API:er – inklusive MIME-typ, ETag, användardefinierade nyckelvärdesmetadata, systemdefinierade metadata och objekttaggar.

Kolumnen _object_metadata kräver Databricks Runtime 18.2 eller högre och är tillgänglig för alla indatafilformat när man läser från molnobjektlagring. Om du vill inkludera _object_metadata kolumnen i den returnerade DataFrame måste du uttryckligen välja den i den läsfråga där du anger källan.

Om datakällan innehåller en kolumn med namnet _object_metadatareturnerar frågor mot _object_metadata datakällkolumnen, inte metadata för molnobjektet. Om du vill komma åt metadatakolumnen för molnobjekt i det här fallet förbereder du ytterligare ett understreck (__object_metadata). Upprepa om __object_metadata det också kolliderar.

Vanliga filmetadata som filsökvägen eller storleken kan efterfrågas med hjälp av _metadata kolumnen. Mer information om kolumnen finns i _metadatakolumnen Filmetadata.

Varning

Nya fält kan läggas till i kolumnen _object_metadata i framtida versioner. Om du vill förhindra schemautvecklingsfel om _object_metadata kolumnen uppdateras kan du välja specifika fält från kolumnen i dina frågor. Se Exempel.

Schema

Kolumnen _object_metadataSTRUCT innehåller följande fält, tillgängliga från och med Databricks Runtime 18.2. Alla fält är nullbara.

Namn	Type	Description	Example
mime_type	STRING	MIME-typ (innehållstyp) för objektet, till exempel application/parquet eller text/csv.	application/parquet
etag	STRING	ETag för objektet. ETags är användbara för att identifiera ändringar eller versionshantering.	"abc123def456"
user_metadata	VARIANT	Användardefinierade nyckel/värde-par för metadata som lagras på objektet. I S3 är dessa till exempel användardefinierade metadatahuvuden. Se Användardefinierade metadatahuvuden i AWS-dokumentationen. I Azure Blob är dessa användardefinierade metadata. Se Hantera blobegenskaper och metadata med .NET i dokumentationen för Azure.	{"my_key":"my_value"}
system_metadata	VARIANT	Systemdefinierade nyckel/värde-par som angetts av molnlagringsleverantören.	{"Content-Length":"1024", ...}
Taggar	VARIANT	Användardefinierade objekttaggnyckel/värde-par som lagras på objektet. I S3 är dessa till exempel objekttaggar. Se Kategorisera dina objekt med hjälp av taggar i AWS-dokumentationen. Alla molnlagringstjänster stöder inte objekttaggar. Se Anteckningar för beteende per leverantör.	{"my_tag":"my_value"}

Exempel

I följande exempel visas hur du läser och frågar _object_metadata efter kolumnen med hjälp av olika inmatningsmetoder.

Läs en grupp filer

I följande exempel läss en CSV-fil och både kolumnerna _metadata och _object_metadata markeras.

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

Strömma filer med Auto Loader

I följande exempel används Auto Loader för att strömma filer från molnlagring och skriver _object_metadata kolumnen till en Delta-tabell.

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)

Välj specifika fält

Om du vill undvika schemautvecklingsfel från framtida ändringar till _object_metadataväljer du endast de specifika fält som du behöver.

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

Använd med COPY INTO

I följande exempel används COPY INTO för att läsa in filer i en Delta-tabell när du väljer _object_metadata kolumnen.

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

Extrahera värden från VARIANT fält

Fälten user_metadata, system_metadataoch tags är VARIANT typ. I följande exempel extraheras specifika värden med hjälp av cast-operatorn :: . Du kan extrahera specifika värden med hjälp av ::-operatorn för typomvandling eller VARIANT-funktionerna. Se 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>`

Notes

Tänk på följande när du använder _object_metadata.

• Kolumnen _object_metadata fungerar med Amazon S3, Azure DFS, Azure Blob och GCP.
• Om något fält från _object_metadata väljs utlöses upp till två ytterligare API-anrop till molnet per fil, så frågor mot ett stort antal små filer kan medföra något ökad latens.
• _object_metadata.tags stöds för S3 och Azure Blob Storage (icke-HNS, blob.core.windows.net). För alla andra leverantörer (Azure DFS, WASB, GCP) returnerar tags{}.
• För S3 måste autentiseringsuppgifterna ha s3:GetObjectTagging behörighet. Om den inte är tillgänglig returnerar tagsnull.
• Om Databricks stöter på ett fel när taggar hämtas från en leverantör som stöds, returnerar tagsnull.
• Systemmetadata, användarmetadata och taggar är inte tillgängliga för Databricks-hanterad lagring och är inställda på null.