Colonna dei metadati dell'oggetto

La _object_metadata colonna è una colonna di metadati nascosta che espone le proprietà a livello di oggetto cloud per ogni file letto da un'origine dati basata su file. A differenza _metadata di (che contiene informazioni come il percorso del file, le dimensioni e il tempo di modifica), _object_metadata fornisce proprietà più avanzate del livello di archiviazione recuperate tramite API cloud, tra cui tipo MIME, ETag, metadati chiave-valore definiti dall'utente, metadati definiti dal sistema e tag di oggetto.

La _object_metadata colonna è disponibile per tutti i formati di file di input durante la lettura dall'archiviazione di oggetti cloud. Per includere la _object_metadata colonna nel dataframe restituito, è necessario selezionarla in modo esplicito nella query di lettura in cui si specifica l'origine.

Se l'origine dati contiene una colonna denominata _object_metadata, le query su _object_metadata restituiscono la colonna dell'origine dati, non i metadati dell'oggetto cloud. Per accedere alla colonna dei metadati dell'oggetto cloud in questo caso, anteporre un carattere di sottolineatura aggiuntivo (__object_metadata). Ripeti se anche __object_metadata va in conflitto.

È possibile eseguire query sui metadati di file comuni, ad esempio il percorso o le dimensioni del file, usando la _metadata colonna . Per altre informazioni sulla _metadata colonna, vedere Colonna metadati file.

Schema

La _object_metadata colonna contiene STRUCT i campi seguenti, disponibili a partire da Databricks Runtime 18.1. Tutti i campi possono essere nulli.

Examples

Negli esempi seguenti viene illustrato come leggere ed eseguire query sulla _object_metadata colonna usando metodi di inserimento diversi.

Leggi un lotto di file

L'esempio seguente legge un file CSV e seleziona le _metadata colonne e _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"))

Trasmettere file con il caricatore automatico

L'esempio seguente usa il caricatore automatico per trasmettere i file dall'archiviazione cloud e scrive la _object_metadata colonna in una tabella 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)

Selezionare campi specifici

Per evitare errori di evoluzione dello schema da modifiche future a _object_metadata, selezionare solo i campi specifici necessari.

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

Da usare con COPY INTO

Nell'esempio seguente viene COPY INTO usato per caricare i file in una tabella Delta durante la selezione della _object_metadata colonna.

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

Estrarre valori dai VARIANT campi

I campi user_metadata, system_metadata e tags sono di tipo VARIANT. L'esempio seguente estrae valori specifici usando l'operatore :: cast. È possibile estrarre valori specifici usando l'operatore :: cast o le funzioni VARIANT. Vedere VARIANT tipo.

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

Note

Tenere presente quanto segue quando si usa _object_metadata.

• La colonna _object_metadata funziona con Amazon S3, Azure DFS, BLOB Azure e GCP.
• La selezione di un qualsiasi campo da _object_metadata attiva fino a due chiamate aggiuntive all'API cloud per file; di conseguenza, le query su un numero elevato di file di piccole dimensioni potrebbero subire un aumento della latenza.
• _object_metadata.tags è supportato per S3 e Archiviazione BLOB di Azure (non HNS, blob.core.windows.net). In tutti gli altri provider (Azure DFS, WASB, GCP), tags restituisce {}.
• Per Amazon S3, le credenziali devono disporre dell'autorizzazione s3:GetObjectTagging. Se non disponibile, tags restituisce null.
• Se Databricks rileva un errore durante il recupero di tag da un provider supportato, tags restituisce null.
• I metadati di sistema, i metadati utente e i tag non sono disponibili per l'archiviazione gestita da Databricks e sono impostati su null.