Trabalhar com o histórico de tabelas

Para as tabelas Apache Iceberg e Delta Lake, cada operação que modifica uma tabela cria uma nova versão da tabela. Use informação histórica para auditar operações, reverter uma tabela ou consultar uma tabela num ponto específico no tempo usando viagens no tempo.

Note

O Databricks não recomenda usar o histórico de tabelas como solução de backup a longo prazo para arquivamento de dados. Use apenas os últimos 7 dias para operações de viagem no tempo, a menos que tenha definido tanto as configurações de dados como de retenção de registos para um valor maior.

Recuperar histórico da tabela

Execute o DESCRIBE HISTORY comando para recuperar informações incluindo as operações, o utilizador e o carimbo temporal de cada gravação numa tabela. As operações são retornadas em ordem cronológica inversa.

A retenção do histórico da tabela é determinada pela configuração da tabela logRetentionDuration, que é de 30 dias por padrão.

Note

A viagem no tempo e o histórico das tabelas são controlados por diferentes limites de retenção. Ver Viagem no tempo.

DESCRIBE HISTORY table_name       -- get the full history of the table

DESCRIBE HISTORY table_name LIMIT 1  -- get the last operation only

Para obter detalhes da sintaxe do Spark SQL, consulte DESCRIBE HISTORY.

Para detalhes da sintaxe em Scala, Java e Python, consulte a documentação da API Delta Lake.

O Explorador de Catálogos mostra visualmente o histórico da tabela no separador Histórico .

Esquema do histórico

A saída da operação history tem as seguintes colunas.

Coluna	Tipo	Description
versão	`long`	A versão da tabela gerada pela operação.
carimbo de data/hora	`timestamp`	Quando esta versão foi cometida.
userId	`string`	O ID do utilizador que executou a operação.
userName	`string`	O nome do utilizador que executou a operação.
operação	`string`	O nome da operação.
parâmetros de operação	`map`	Os parâmetros da operação (por exemplo, predicados.)
tarefa	`struct`	Os detalhes da tarefa do Lakeflow que executou a operação. É preenchido apenas para commits efetuados por uma tarefa do Lakeflow. Caso contrário, `null`.
bloco de notas	`struct`	Os detalhes do caderno Databricks a partir do qual a operação foi executada. É preenchido apenas para commits efetuados a partir de um notebook do Databricks. Caso contrário, `null`.
clusterId	`string`	O ID do cluster onde a operação decorria.
lerVersão	`long`	A versão da tabela que foi lida para realizar a operação de escrita.
isolationLevel	`string`	O nível de isolamento utilizado nesta operação.
isBlindAppend	`boolean`	Se esta operação anexou dados.
operationMetrics	`map`	As métricas da operação (por exemplo, número de linhas e ficheiros modificados.)
userMetadata	`string`	Os metadados de commit definidos pelo utilizador, caso tenham sido especificados.

+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|version|          timestamp|userId|userName|operation| operationParameters| job|notebook|clusterId|readVersion|   isolationLevel|isBlindAppend|    operationMetrics|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|      5|2019-07-29 14:07:47|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          4|WriteSerializable|        false|[numTotalRows -> ...|
|      4|2019-07-29 14:07:41|   ###|     ###|   UPDATE|[predicate -> (id...|null|     ###|      ###|          3|WriteSerializable|        false|[numTotalRows -> ...|
|      3|2019-07-29 14:07:29|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          2|WriteSerializable|        false|[numTotalRows -> ...|
|      2|2019-07-29 14:06:56|   ###|     ###|   UPDATE|[predicate -> (id...|null|     ###|      ###|          1|WriteSerializable|        false|[numTotalRows -> ...|
|      1|2019-07-29 14:04:31|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          0|WriteSerializable|        false|[numTotalRows -> ...|
|      0|2019-07-29 14:01:40|   ###|     ###|    WRITE|[mode -> ErrorIfE...|null|     ###|      ###|       null|WriteSerializable|         true|[numFiles -> 2, n...|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+

Note

Se escrever numa tabela usando os seguintes métodos, algumas colunas não estão disponíveis:
As colunas adicionadas no futuro serão sempre adicionadas após a última coluna.

Compreensão `partitionBy` dos parâmetros de operação

O partitionBy campo no histórico da tabela só tem significado para operações CREATE e OVERWRITE que definem ou alteram o esquema de partição de uma tabela.

Para operações de acréscimo a tabelas existentes (APPEND, INSERT, UPDATE, DELETE, MERGE), este campo pode mostrar uma matriz [] vazia ou colunas de partição, dependendo do método de gravação usado (.save() vs .saveAsTable()).

Esta inconsistência é um comportamento esperado e não afeta a forma como os dados são escritos nas partições. Não deves usá-lo para validar operações de anexação.

Example

Considere uma tabela particionada pela date coluna. Quando crias a tabela, partitionBy é preenchido:

df.write.format("delta") \
  .partitionBy("date") \
  .saveAsTable("sales_data")

A operação CREATE no histórico mostra:

operationParameters: {
  "mode": "ErrorIfExists",
  "partitionBy": "[\"date\"]"
}

Quando adiciona dados a esta tabela, partitionBy mostra um array vazio:

new_df.write.format("delta") \
  .mode("append") \
  .saveAsTable("sales_data")

A operação APPEND mostra:

operationParameters: {
  "mode": "Append",
  "partitionBy": "[]"
}

O valor vazio partitionBy é esperado. Os dados ainda são gravados nas partições corretas com base no esquema de partição existente da tabela. Tenha em atenção que .save() para um caminho pode mostrar colunas de partição neste campo, mas esta diferença é um detalhe de implementação e não afeta o comportamento de escrita.

Métricas de operação

A operação history retorna uma coleção de métricas de operações no mapa de colunas operationMetrics.

As tabelas a seguir listam as definições de chave do mapa por operação.