Compartilhar via

Coluna de metadados de arquivo

Você pode obter informações de metadados para arquivos de entrada com a coluna _metadata. A coluna _metadata é uma coluna oculta e está disponível para todos os formatos de arquivo de entrada. Para incluir a _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 nomeada _metadata, as consultas retornarão a coluna da fonte de dados e não os metadados do arquivo.

Aviso

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

Metadados com suporte

A coluna _metadata é um STRUCT que contém os seguintes campos:

Nome Tipo Descrição Exemplo Versão Mínima do Databricks Runtime
file_path STRING O caminho do arquivo do arquivo de entrada. file:/tmp/f0.csv 10.5
file_name STRING Nome do arquivo de entrada junto com sua extensão. f0.csv 10.5
file_size LONG Tamanho do arquivo de entrada em bytes. 628 10.5
tempo_de_modificação_do_arquivo TIMESTAMP Carimbo de data/hora da última modificação do arquivo de entrada. 2021-12-20 20:05:21 10.5
file_block_start LONG Deslocamento inicial do bloco que está sendo lido, em bytes. 0 13,0
comprimento_do_arquivo_bloco LONG Comprimento do bloco que está sendo lido, em bytes. 628 13,0

Exemplos

Usar em um leitor de fonte de dados baseado em arquivo básico

Pitão

df = spark.read \
  .format("csv") \
  .schema(schema) \
  .load("dbfs:/tmp/*") \
  .select("*", "_metadata")

display(df)

'''
Result:
+---------+-----+----------------------------------------------------+
|   name  | age |                 _metadata                          |
+=========+=====+====================================================+
|         |     | {                                                  |
|         |     |    "file_path": "dbfs:/tmp/f0.csv",                |
| Debbie  | 18  |    "file_name": "f0.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-07-02 01:05:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
|         |     | {                                                  |
|         |     |    "file_path": "dbfs:/tmp/f1.csv",                |
| Frank   | 24  |    "file_name": "f1.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-12-20 02:06:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
'''

Scala (linguagem de programação)

val df = spark.read
  .format("csv")
  .schema(schema)
  .load("dbfs:/tmp/*")
  .select("*", "_metadata")

display(df_population)

/* Result:
+---------+-----+----------------------------------------------------+
|   name  | age |                 _metadata                          |
+=========+=====+====================================================+
|         |     | {                                                  |
|         |     |    "file_path": "dbfs:/tmp/f0.csv",                |
| Debbie  | 18  |    "file_name": "f0.csv",                          |
|         |     |    "file_size": 12,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-07-02 01:05:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
|         |     | {                                                  |
|         |     |    "file_path": "dbfs:/tmp/f1.csv",                |
| Frank   | 24  |    "file_name": "f1.csv",                          |
|         |     |    "file_size": 10,                                |
|         |     |    "file_block_start": 0,                          |
|         |     |    "file_block_length": 12,                        |
|         |     |    "file_modification_time": "2021-12-20 02:06:21" |
|         |     | }                                                  |
+---------+-----+----------------------------------------------------+
*/

Selecionar campos específicos

Pitão

spark.read \
  .format("csv") \
  .schema(schema) \
  .load("dbfs:/tmp/*") \
  .select("_metadata.file_name", "_metadata.file_size")

Scala (linguagem de programação)

spark.read
  .format("csv")
  .schema(schema)
  .load("dbfs:/tmp/*")
  .select("_metadata.file_name", "_metadata.file_size")

Usar em filtros

Pitão

spark.read \
  .format("csv") \
  .schema(schema) \
  .load("dbfs:/tmp/*") \
  .select("*") \
  .filter(col("_metadata.file_name") == lit("test.csv"))

Scala (linguagem de programação)

spark.read
  .format("csv")
  .schema(schema)
  .load("dbfs:/tmp/*")
  .select("*")
  .filter(col("_metadata.file_name") === lit("test.csv"))

Usar em COPY INTO (herdado)

COPY INTO my_delta_table
FROM (
  SELECT *, _metadata FROM 'abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData'
)
FILEFORMAT = CSV

Usar no Carregador Automático

Se os dados de origem contiverem uma coluna nomeada _metadata, renomeie-a para source_metadata. Se você não renomeá-la, não poderá acessar a coluna de metadados do arquivo na tabela de destino; em vez disso, as consultas retornarão a coluna de origem.

Pitão

spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .schema(schema) \
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData") \
  .selectExpr("*", "_metadata as source_metadata") \
  .writeStream \
  .option("checkpointLocation", checkpointLocation) \
  .start(targetTable)

Scala (linguagem de programação)

spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .schema(schema)
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData")
  .selectExpr("*", "_metadata as source_metadata")
  .writeStream
  .option("checkpointLocation", checkpointLocation)
  .start(targetTable)

Se você usar foreachBatch e quiser incluir a coluna de metadados de arquivo no DataFrame de streaming, deverá referenciá-la no DataFrame de leitura de streaming antes da foreachBatch função. Se você fizer referência apenas à coluna de metadados do arquivo dentro da foreachBatch função, a coluna não será incluída.

Pitão

spark.readStream \
  .format("cloudFiles") \
  .option("cloudFiles.format", "csv") \
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData") \
  .select("*", "metadata") \
  .writeStream \
  .foreachBatch(...)

Scala (linguagem de programação)

spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "csv")
  .load("abfss://my-container-name@storage-account-name.dfs.core.windows.net/csvData")
  .select("*", "metadata")
  .writeStream
  .foreachBatch(...)