Table history schema and operation metrics

The DESCRIBE HISTORY command returns 14 columns for Apache Iceberg and Delta Lake tables that describe the history of table operations. Use this reference to interpret each column.

For guidance on retrieving table history, querying earlier table versions, and restoring a table, see Work with table history.

History schema

The output of the history operation has the following columns.

Column	Type	Description
version	`long`	The table version generated by the operation.
timestamp	`timestamp`	When this version was committed.
userId	`string`	The ID of the user that ran the operation.
userName	`string`	The name of the user that ran the operation.
operation	`string`	The name of the operation.
operationParameters	`map`	The parameters of the operation (for example, predicates.) For `OPTIMIZE` operations, these parameters identify the type of operation. See Identify the type of `OPTIMIZE` operation.
job	`struct`	The details of the Lakeflow job that ran the operation. Populates only for commits written from a Lakeflow job. Otherwise, `null`.
notebook	`struct`	The details of the Databricks notebook from which the operation was run. Populates only for commits written from a Databricks notebook. Otherwise, `null`.
clusterId	`string`	The ID of the cluster on which the operation ran.
readVersion	`long`	The version of the table that was read to perform the write operation.
isolationLevel	`string`	The isolation level used for this operation.
isBlindAppend	`boolean`	Whether this operation appended data.
operationMetrics	`map`	The metrics of the operation (for example, number of rows and files modified.)
userMetadata	`string`	The user-defined commit metadata if it was specified.

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

If you write into a table using the following methods, some columns aren't available:
Columns added in the future will always be added after the last column.

Understanding `partitionBy` in operation parameters

The partitionBy field in table history is only meaningful for CREATE and OVERWRITE operations that define or change a table's partition schema.

For append operations to existing tables (APPEND, INSERT, UPDATE, DELETE, MERGE), this field might show an empty array [] or partition columns depending on the write method used (.save() vs .saveAsTable()).

This inconsistency is expected behavior and doesn't affect how data is written to partitions. You shouldn't use it to validate append operations.

Example

Consider a table partitioned by the date column. When you create the table, partitionBy is populated:

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

The CREATE operation in history shows:

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

When you append data to this table, partitionBy shows an empty array:

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

The APPEND operation shows:

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

The empty partitionBy value is expected. The data is still written to the correct partitions based on the table's existing partition schema. Note that .save() to a path might show partition columns in this field, but this difference is an implementation detail and doesn't affect write behavior.

Operation metrics

The history operation returns a collection of operation metrics in the operationMetrics column map.

The following tables list the map key definitions by operation.