Coluna de metadados de objeto

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

A _object_metadata coluna é uma coluna de metadados oculta que expõe propriedades no nível do objeto de nuvem para cada arquivo lido por uma fonte de dados baseada em arquivo. Ao contrário _metadata (que contém informações como caminho de arquivo, tamanho e tempo de modificação), _object_metadata fornece propriedades mais avançadas de camada de armazenamento buscadas por meio de APIs de nuvem , incluindo tipo MIME, ETag, metadados chave-valor definidos pelo usuário, metadados definidos pelo sistema e marcas de objeto.

A _object_metadata coluna está disponível para todos os formatos de arquivo de entrada ao ler do armazenamento de objetos de nuvem. Para incluir a _object_metadata coluna no DataFrame retornado, você deve selecioná-la explicitamente na consulta de leitura na qual especificar a origem.

Se a fonte de dados contiver uma coluna chamada _object_metadata, as consultas em _object_metadata retornarão a coluna da fonte de dados, não os metadados do objeto na nuvem. Para acessar a coluna de metadados do objeto de nuvem nesse caso, acrescente um sublinhado adicional (__object_metadata). Repita o processo se __object_metadata também colidir.

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

Warning

Novos campos poderão ser adicionados à coluna _object_metadata em versões futuras. Para evitar erros de evolução do esquema se a _object_metadata coluna for atualizada, você poderá selecionar campos específicos da coluna em suas consultas. Veja exemplos.

Schema

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

Nome Tipo Description Example
mime_type STRING Tipo MIME (tipo de conteúdo) do objeto, por exemplo application/parquet ou text/csv. application/parquet
etag STRING ETag do objeto. As ETags são úteis para detectar alterações ou controle de versão. "abc123def456"
user_metadata VARIANT Pares chave-valor de metadados definidos pelo usuário armazenados no objeto. Por exemplo, no S3, são cabeçalhos de metadados definidos pelo usuário. Consulte os cabeçalhos de metadados definidos pelo usuário na documentação do AWS. Em Azure Blob, são metadados definidos pelo usuário. Consulte Gerenciar propriedades e metadados de blob com o .NET na documentação do Azure. {"my_key":"my_value"}
system_metadata VARIANT Pares de chave-valor definidos pelo provedor de armazenamento em nuvem. {"Content-Length":"1024", ...}
Tags VARIANT Pares de chave-valor de tags de objeto definidas pelo usuário armazenados no objeto. Por exemplo, no S3 estas são as tags de objeto. Consulte Categorizar seus objetos usando marcas na documentação do AWS. Nem todos os serviços de armazenamento em nuvem dão suporte a marcas de objeto. Consulte Anotações sobre o comportamento por provedor. {"my_tag":"my_value"}

Exemplos

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

Ler um lote de arquivos

O exemplo a seguir lê um arquivo CSV e seleciona 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 arquivos com o Carregador Automático

O exemplo a seguir usa o Carregador Automático para transmitir arquivos do armazenamento em nuvem e grava a _object_metadata coluna em uma 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 do esquema devido a alterações futuras em _object_metadata, selecione apenas os campos específicos de que você 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")

Usar com COPY INTO

O exemplo a seguir usa COPY INTO para carregar arquivos em uma tabela Delta ao selecionar a _object_metadata coluna.

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

Extrair valores de VARIANT campos

Os campos user_metadata, system_metadata e tags são do tipo VARIANT. O exemplo a seguir extrai valores específicos usando o :: operador de conversão. Você pode extrair valores específicos usando o operador de conversão :: ou 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>`

Anotações

Tenha o seguinte em mente ao usar _object_metadata.

  • A coluna _object_metadata funciona com Amazon S3, Azure DFS, Azure Blob e GCP.
  • Selecionar qualquer campo em _object_metadata aciona até duas chamadas adicionais à API na nuvem por arquivo, portanto consultas em um grande número de arquivos pequenos podem sofrer algum aumento de latência.
  • _object_metadata.tags tem suporte para S3 e Armazenamento de Blobs do Azure (não HNS, blob.core.windows.net). Em todos os outros provedores (Azure DFS, WASB, GCP), tags retorna {}.
  • Para o S3, a credencial deve ter a permissão s3:GetObjectTagging. Se não estiver disponível, tags retornará null.
  • Se o Databricks encontrar um erro ao recuperar tags de um provedor compatível, tags retornará null.
  • Metadados do sistema, metadados de usuário e marcas não estão disponíveis para armazenamento gerenciado pelo Databricks e são definidos como null.
  • Last updated on