Inspeccionar metadados da tabela Delta

Usar DESCRIBE DETAIL e DESCRIBE HISTORY quando precisar de inspecionar uma tabela Delta sem a alterar. Estes comandos ajudam-no a perceber como uma tabela é armazenada, o que mudou ao longo do tempo e qual a versão da tabela que poderá querer investigar ou restaurar.

Os dois comandos são comandos de inspeção só de leitura. Eles não modificam dados de tabelas, metadados ou histórico de transações.

Use DESCREVER EM DETALHE

DESCRIBE DETAIL retorna metadados ao nível da tabela para uma tabela Delta. Usa-o quando quiseres uma rápida captura da definição da tabela e dos detalhes de armazenamento.

Os metadados típicos incluem:

  • Formato de tabela
  • Identificador e nome da tabela
  • Localização em OneLake
  • Tempo de criação e tempo de última modificação
  • Colunas de partição
  • Número de ficheiros e tamanho total em bytes
  • Propriedades da tabela
  • Versões mínimas do protocolo de leitor e escritor

Executar DESCRIBE DETAIL

Executa DESCRIBE DETAIL contra uma tabela Delta usando SQL Spark ou a API Delta Lake em PySpark ou Scala.

DESCRIBE DETAIL schema_name.table_name

Compreenda a saída DESCRIBE DETAIL

O esquema exato pode variar consoante o tempo de execução e as características da tabela, mas é comum ver as colunas seguintes.

Coluna O que significa
format O formato de tabela. Para tabelas Delta em Fabric, este valor é delta.
id O identificador único para a tabela Delta.
name O nome da tabela registada.
location O caminho de armazenamento da tabela no OneLake.
createdAt A marca temporal da criação da tabela.
lastModified O carimbo temporal em que os metadados ou ficheiros 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 ficheiros de dados acompanhados pela tabela.
sizeInBytes O tamanho total dos dados da tabela rastreada em bytes.
properties As propriedades da tabela são armazenadas com a 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 de escrita exigida pelo protocolo Delta para escrever na tabela.

Use estes valores para confirmar onde uma tabela reside, estimar a área de armazenamento, verificar a partição e verificar se as propriedades da tabela ou as versões do protocolo mudaram.

Utilizar DESCRIBE HISTORY

DESCRIBE HISTORY devolve o histórico das operações de uma tabela Delta. Utilize-o quando precisar de um registo de auditoria das operações de escrita e de manutenção, como WRITE, MERGE, OPTIMIZE, VACUUM, DELETE ou UPDATE.

Esta história ajuda-o a responder a perguntas como:

  • Quem mudou a mesa?
  • Que operação foi executada?
  • Quando é que a mudança aconteceu?
  • Qual versão deve inspecionar com viagem no tempo ou restauração?

Executar DESCRIBE HISTORY

Execute DESCRIBE HISTORY para devolver todo o histórico disponível.

DESCRIBE HISTORY schema_name.table_name

Limita a saída quando só precisares das entradas mais recentes.

DESCRIBE HISTORY schema_name.table_name LIMIT n

Entender a saída de DESCRIBE HISTORY

O resultado do histórico é um registo de auditoria das transações Delta. As colunas seguintes são especialmente úteis.

Coluna O que significa
version A versão da tabela Delta criada pela operação.
timestamp O momento em que a operação se realizou.
operation O tipo de operação, como WRITE, MERGE, OPTIMIZE, ou VACUUM.
operationParameters Parâmetros fornecidos para a operação.
operationMetrics Métricas capturadas para a operação, como ficheiros adicionados, ficheiros removidos, linhas escritas ou volume de dados processado.
userName O utilizador ou principal associado à operação, quando disponível.
Informações do portátil Contexto relacionado com o bloco de notas, como o caminho ou o ID do bloco de notas, quando a operação teve origem numa execução do bloco de notas.

Utilize operationParameters e operationMetrics em conjunto quando precisar de mais do que apenas o nome da operação. Por exemplo, as entradas OPTIMIZE e VACUUM incluem frequentemente métricas que ajudam a compreender quanta quantidade de dados o Fabric reescreveu ou limpou.

Quando utilizar DESCRIBE HISTORY

DESCRIBE HISTORY é especialmente útil nestes cenários:

  • Registo de auditoria: Veja quem alterou uma tabela e que operação executou.
  • Depuração: Identifique a operação de escrita, fusão, otimização ou eliminação que introduziu um problema.
  • Descoberta de versões: Encontre a versão da tabela para usar com viagens no tempo ou RESTORE.
  • Monitorização de manutenção: Inspecione as métricas OPTIMIZE e VACUUM para confirmar que a manutenção foi executada e para ver que alterações efetuou.

Onde executar estes comandos

Executa estes comandos nos notebooks Fabric e nas definições de trabalhos do Spark quando trabalhares com tabelas Delta através do Apache Spark.

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

Retenção histórica

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

Se precisar de inspecionar histórico antigo, confirme que as definições de retenção de tabela mantêm o registo de transações tempo suficiente para os seus requisitos operacionais e de auditoria.

Conteúdo relacionado

  • Last updated on