Pular para o conteúdo principal
Última atualização em

Coluna de metadados do objeto

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

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

A coluna _object_metadata está disponível para todos os formatos de arquivo de entrada ao ler do armazenamento de objetos cloud . Para incluir a coluna _object_metadata no DataFrame retornado, você deve selecioná-la explicitamente na consulta de leitura onde você especifica 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 cloud . Para acessar a coluna de metadados do objeto cloud neste caso, adicione um sublinhado adicional (__object_metadata). Repita se __object_metadata também colidir.

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

atenção

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

Esquema​

A coluna _object_metadata é um STRUCT contendo os seguintes campos, disponíveis a partir do Databricks Runtime 18.1. Todos os campos podem ser nulos.

Nome

Tipo

Descrição

Exemplo

tipo_mime

STRING

Tipo MIME (tipo de conteúdo) do objeto, por exemplo application/parquet ou text/csv.

application/parquet

etag

STRING

ETag do objeto. Os ETags são úteis para detectar alterações ou controlar versões.

"abc123def456"

metadados do usuário

VARIANT

Metadados definidos pelo usuário, no formato key-valor, armazenados no objeto. Por exemplo, no S3, esses são cabeçalhos de metadados definidos pelo usuário. Consulte a seção "Cabeçalhos de metadados definidos pelo usuário" na documentação da AWS. No Azure Blob, esses são metadados definidos pelo usuário. Consulte a documentação Azure para obter informações sobre como gerenciar propriedades e metadados de blobs com .NET .

{"my_key":"my_value"}

metadados do sistema

VARIANT

Parâmetro definido pelo sistema - key-valor definido pelo provedor de armazenamento cloud .

{"Content-Length":"1024", ...}

Tags

VARIANT

tag de objeto definida pelo usuário, par key-valor armazenado no objeto. Por exemplo, no S3, essas são tags de objeto. Consulte a seção "Categorizando seus objetos usando tags" na documentação da AWS. Nem todos os serviços de armazenamento cloud suportam tags de objeto. Consulte as Notas para obter informações sobre o comportamento de cada prestador de serviços.

{"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.

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

arquivos de transmissão com Auto Loader​

O exemplo a seguir usa Auto Loader para transmitir arquivos do armazenamento cloud e grava a coluna _object_metadata 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)

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

Usar com COPY INTO​

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

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

Extrair valores dos campos VARIANT​

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 funções VARIANT . Veja o tipoVARIANT.

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

Notas​

Ao usar _object_metadata, tenha em mente o seguinte.

  • A coluna _object_metadata funciona com Amazon S3, Azure DFS, Azure Blob e GCP.
  • Selecionar qualquer campo de _object_metadata aciona até duas chamadas adicionais API cloud por arquivo, portanto, consultas em um grande número de arquivos pequenos podem apresentar algum aumento de latência.
  • _object_metadata.tags é suportado para S3 e Armazenamento Azure Blob (não-HNS, blob.core.windows.net). Em todos os outros provedores (Azure DFS, WASB, GCP), tags retorna {}.
  • Para S3, a credencial deve ter permissão s3:GetObjectTagging . Se não estiver disponível, tags retorna null.
  • Se o Databricks encontrar um erro ao buscar tags de um provedor compatível, tags retorna null.
  • Os metadados do sistema, os metadados do usuário e tags não estão disponíveis para o armazenamento Databricks-gerenciar e estão definidos como null.
Nesta página