Coluna de metadados do objeto

A _object_metadata coluna é uma coluna oculta de metadados que expõe propriedades ao nível do objeto da nuvem para cada ficheiro lido por uma fonte de dados baseada em ficheiros. O Different _metadata (que contém informações como caminho do ficheiro, tamanho e tempo de modificação), _object_metadata fornece propriedades de camada de armazenamento mais avançadas obtidas através de APIs cloud — incluindo tipo MIME, ETag, metadados-chave-valor definidos pelo utilizador, metadados definidos pelo sistema e etiquetas de objetos.

A _object_metadata coluna requer Databricks Runtime 18.2 ou superior e está disponível para todos os formatos de ficheiro de entrada ao ler a partir de armazenamento de objetos na cloud. Para incluir a _object_metadata coluna no DataFrame retornado, você deve selecioná-la explicitamente na consulta de leitura onde você especifica a fonte.

Se a fonte de dados contiver uma coluna com o nome _object_metadata, as consultas a _object_metadata devolvem a coluna da fonte de dados, e não os metadados do objeto na cloud. Para aceder à coluna de metadados do objeto cloud neste caso, introduza um sublinhado adicional (__object_metadata). Repita o processo se __object_metadata também colidir.

Metadados comuns de ficheiros, como o caminho ou o tamanho do ficheiro, podem ser consultados usando a _metadata coluna. Para mais informações sobre a _metadata coluna, consulte a coluna de metadados do ficheiro.

Schema

A _object_metadata coluna contém STRUCT os seguintes campos, disponíveis a partir do Databricks Runtime 18.2. Todos os campos são anuláveis.

Exemplos

Os exemplos seguintes mostram como ler e consultar a coluna _object_metadata recorrendo a diferentes métodos de ingestão.

Leia um lote de ficheiros

O exemplo seguinte lê um ficheiro CSV e seleciona ambas as colunas _metadata 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"))

Transmitir ficheiros com o Auto Loader

O exemplo seguinte utiliza o Auto Loader para transmitir ficheiros a partir do armazenamento na cloud e escreve a _object_metadata coluna numa tabela 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)

Selecionar campos específicos

Para evitar erros de evolução de esquema devido a alterações futuras para _object_metadata, selecione apenas os campos específicos de que precisa.

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

Utilização com COPY INTO

O exemplo seguinte é usado COPY INTO para carregar ficheiros numa tabela Delta enquanto se seleciona a _object_metadata coluna.

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

Extrair valores dos VARIANT campos

Os campos user_metadata, system_metadata e tags são do tipo VARIANT. O exemplo seguinte extrai valores específicos usando o :: operador cast. Pode extrair valores específicos com o operador de conversão :: ou com as funções VARIANT. Consulte 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>`

Notes

Tenha em mente o seguinte ao usar _object_metadata.

• A coluna _object_metadata funciona com Amazon S3, Azure DFS, Azure Blob e GCP.
• Selecionar qualquer campo a partir de _object_metadata disparar até duas chamadas adicionais de API na nuvem por ficheiro, pelo que consultas sobre um grande número de ficheiros pequenos podem experienciar algum aumento de latência.
• _object_metadata.tags é suportado para S3 e Armazenamento de Blobs do Azure (não-HNS, blob.core.windows.net). Em todos os outros fornecedores (Azure DFS, WASB, GCP), tags devolve {}.
• Para o S3, a credencial deve ter a permissão s3:GetObjectTagging. Se não estiver disponível, tags devolve null.
• Se o Databricks encontrar um erro ao obter etiquetas de um fornecedor suportado, tags devolve null.
• Metadados do sistema, metadados de utilizador e etiquetas não estão disponíveis para armazenamento gerido pelo Databricks e estão definidos para null.