Inspecionar metadados da tabela Delta

Use DESCRIBE DETAIL e DESCRIBE HISTORY quando precisar inspecionar uma tabela Delta sem alterá-la. Esses comandos ajudam você a entender como uma tabela é armazenada, o que foi alterado ao longo do tempo e qual versão da tabela você pode querer investigar ou restaurar.

Ambos os comandos são comandos de inspeção somente para leitura. Eles não modificam dados de tabela, metadados ou histórico de transações.

Usar DESCREVA DETALHES

DESCRIBE DETAIL retorna metadados de nível de tabela para uma tabela Delta. Use-o quando quiser um instantâneo rápido da definição da tabela e dos detalhes de armazenamento.

Metadados típicos incluem:

  • Formato de tabela
  • Identificador e nome da tabela
  • Localização do OneLake
  • Hora de criação e hora da última modificação
  • Colunas de particionamento
  • Contagem de arquivos e tamanho total em bytes
  • Propriedades da tabela
  • Versões mínimas de protocolo de leitor e gravador

Execute DESCRIBE DETAIL

Execute DESCRIBE DETAIL em relação a uma tabela Delta usando o Spark SQL ou a API do Delta Lake no PySpark ou no Scala.

DESCRIBE DETAIL schema_name.table_name

Entender a saída DESCREVA DETALHES

O esquema exato pode variar de acordo com os recursos de runtime e tabela, mas você geralmente vê as colunas a seguir.

Column O que significa
format O formato da tabela. Para tabelas Delta em Fabric, esse valor é delta.
id O identificador exclusivo da tabela Delta.
name O nome da tabela registrada.
location O caminho de armazenamento da tabela no OneLake.
createdAt A data e hora em que a tabela foi criada.
lastModified O registro de data e hora em que os metadados ou os arquivos da tabela foram atualizados pela última vez.
partitionColumns A lista de colunas de partição definidas para a tabela.
numFiles O número atual de arquivos de dados rastreados pela tabela.
sizeInBytes O tamanho total dos dados da tabela rastreada em bytes.
properties As propriedades da tabela armazenadas na definição da tabela Delta.
minReaderVersion A versão mínima do leitor de protocolo Delta necessária para ler a tabela.
minWriterVersion A versão mínima do gravador de protocolo Delta necessária para gravar na tabela.

Use esses valores para confirmar onde uma tabela reside, estimar o volume de armazenamento, verificar o particionamento e verificar se as propriedades da tabela ou as versões de protocolo foram alteradas.

Use DESCRIBE HISTORY

DESCRIBE HISTORY retorna o histórico de nível de operação de uma tabela Delta. Use isso quando precisar de um registro de auditoria de operações de gravação e atividades de manutenção, como WRITE, MERGE, OPTIMIZE, VACUUM, DELETE ou UPDATE.

Esse histórico ajuda você a responder perguntas como:

  • Quem mudou a tabela?
  • Qual operação foi executada?
  • Quando a mudança aconteceu?
  • Qual versão você deve inspecionar usando o recurso de voltar no tempo ou restaurar?

Executar DESCRIBE HISTORY

Execute DESCRIBE HISTORY para retornar o histórico completo disponível.

DESCRIBE HISTORY schema_name.table_name

Limite a saída quando você precisar apenas das entradas mais recentes.

DESCRIBE HISTORY schema_name.table_name LIMIT n

Entenda a saída do comando DESCRIBE HISTORY

A saída de histórico é um log de auditoria de transações Delta. As colunas a seguir são especialmente úteis.

Column O que significa
version A versão da tabela Delta criada pela operação.
timestamp O horário em que a operação foi efetivada.
operation O tipo de operação, como WRITE, MERGE, OPTIMIZEou VACUUM.
operationParameters Parâmetros que foram fornecidos para a operação.
operationMetrics Métricas capturadas para a operação, como arquivos adicionados, arquivos removidos, linhas gravadas ou volume de dados processado.
userName O usuário ou principal associado à operação, quando disponíveis.
informações do notebook Contexto relacionado ao notebook, como o caminho do notebook ou o ID do notebook, quando a operação se originou de uma execução de notebook.

Use operationParameters e operationMetrics juntos quando precisar de mais do que o nome da operação. Por exemplo, as entradas OPTIMIZE e VACUUM geralmente incluem métricas que ajudam você a entender a quantidade de dados que Fabric reescreveu ou limpou.

Quando usar DESCRIBE HISTORY

DESCRIBE HISTORY é especialmente útil nestes cenários:

  • Trilha de auditoria: examine quem alterou uma tabela e qual operação executou.
  • Depuração: Identifique a operação de gravação, mesclagem, otimização ou exclusão que causou um problema.
  • Descoberta de versão: localize a versão da tabela a ser usada com viagem no tempo ou RESTORE.
  • Monitoramento de manutenção: inspecione OPTIMIZE e VACUUM as métricas para confirmar se a manutenção foi executada e ver o que ela mudou.

Onde executar esses comandos

Execute esses comandos em Fabric notebooks e definições de trabalho do Spark ao trabalhar com tabelas Delta por meio do Apache Spark.

DESCRIBE DETAIL também funciona no endpoint de análise SQL para cenários básicos de metadados de tabela. Use o Spark quando precisar de APIs completas do Delta Lake, como DeltaTable.forName(...).detail() ou DeltaTable.forName(...).history() em PySpark ou Scala.

Retenção de histórico

A retenção do histórico do Delta é controlada pela propriedade delta.logRetentionDuration da tabela. O período de retenção padrão é de 30 dias.

Se você precisar inspecionar o histórico mais antigo, confirme se as configurações de retenção da tabela preservam o log de transações por tempo suficiente para seus requisitos operacionais e de auditoria.

Conteúdo relacionado

  • Last updated on