Esquema do histórico da tabela e métricas de operações

O comando DESCRIBE HISTORY retorna 14 colunas para tabelas Apache Iceberg e Delta Lake que descrevem a história das operações da tabela. Use esta referência para interpretar cada coluna.

Para obter orientações sobre como recuperar o histórico da tabela, consultar versões anteriores da tabela e restaurar uma tabela, consulte Trabalhar com o histórico da tabela.

Esquema de história

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

Coluna	Tipo	Descrição
version	`long`	A versão da tabela gerada pela operação.
carimbo de data/hora	`timestamp`	Quando essa versão foi confirmada.
userId	`string`	O ID do usuário que executou a operação.
userName	`string`	O nome do usuário que executou a operação.
operation	`string`	O nome da operação.
operationParameters	`map`	Os parâmetros da operação (por exemplo, predicados.) Para operações `OPTIMIZE`, esses parâmetros identificam o tipo de operação. Consulte Identificar o tipo de operação `OPTIMIZE`.
Job	`struct`	Os detalhes do Lakeflow job que executou a operação. Preenchido apenas para commits gravados a partir de um LakeFlow Job. Caso contrário, `null`.
notebook	`struct`	Os detalhes do notebook do Databricks a partir do qual a operação foi executada. Preenchido somente para commits gravados a partir de um notebook do Databricks. Caso contrário, `null`.
clusterId	`string`	O ID do cluster no qual a operação foi executada.
readVersion	`long`	Versão da tabela que foi lida para realizar a operação de gravação.
isolationLevel	`string`	Nível de isolamento usado para esta operação.
isBlindAppend	`boolean`	Se essa operação anexou dados.
operationMetrics	`map`	As métricas da operação (por exemplo, número de linhas e arquivos modificados).
userMetadata	`string`	Os metadados de commit definidos pelo usuário, se tiverem sido especificados.

Coluna	Tipo	Descrição
version	`long`	A versão da tabela gerada pela operação.
carimbo de data/hora	`timestamp`	Quando essa versão foi confirmada.
userId	`string`	O ID do usuário que executou a operação.
userName	`string`	O nome do usuário que executou a operação.
operation	`string`	O nome da operação.
operationParameters	`map`	Os parâmetros da operação (por exemplo, predicados.) Para operações `OPTIMIZE`, esses parâmetros identificam o tipo de operação. Consulte Identificar o tipo de operação `OPTIMIZE`.
Job	`struct`	Os detalhes do Lakeflow job que executou a operação. Preenchido apenas para commits gravados a partir de um LakeFlow Job. Caso contrário, `null`.
notebook	`struct`	Os detalhes do notebook do Databricks a partir do qual a operação foi executada. Preenchido somente para commits gravados a partir de um notebook do Databricks. Caso contrário, `null`.
clusterId	`string`	O ID do cluster no qual a operação foi executada.
readVersion	`long`	Versão da tabela que foi lida para realizar a operação de gravação.
isolationLevel	`string`	Nível de isolamento usado para esta operação.
isBlindAppend	`boolean`	Se essa operação anexou dados.
operationMetrics	`map`	As métricas da operação (por exemplo, número de linhas e arquivos modificados).
userMetadata	`string`	Os metadados de commit definidos pelo usuário, se tiverem sido especificados.

Text
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|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...|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+

nota

Se você gravar em uma tabela usando os seguintes métodos, algumas colunas não estarão disponíveis:
As colunas adicionadas no futuro serão sempre adicionadas após a última coluna.

Compreendendo `partitionBy` nos parâmetros de operação

O campo partitionBy na história da tabela só é significativo para operações CREATE e OVERWRITE que definem ou alteram o esquema de partição de uma tabela.

Para operações de append em 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()).

Essa inconsistência é um comportamento esperado e não afeta a forma como os dados são gravados nas partições. Você não deve usá-lo para validar operações de append.

Exemplo

Considere uma tabela particionada pela coluna date. Quando você cria a tabela, partitionBy é preenchido:

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

A operações CREATE no história mostra:

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

Ao adicionar dados a esta tabela, partitionBy mostra uma matriz vazia:

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

A operação APPEND mostra:

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

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

Métricas de operação

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

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