DESCRIBE HISTORY

Returns the version history of a Delta table, showing each commit's version number, timestamp, operation type, operation metrics, file statistics, and isolation level.

Category: table-infoDeltaForge extension

Syntax

DESCRIBE HISTORY <table> [LIMIT <n>]

Description

## Overview DESCRIBE HISTORY reads the Delta transaction log and returns one row per commit, providing a complete audit trail of every operation performed on the table. This is essential for understanding table evolution, diagnosing issues, and identifying time travel restoration points. ## Behavior The engine reads commit entries from the Delta transaction log (JSON files in the _delta_log directory) and extracts detailed metadata for each version. The result set contains the following columns: | Column | Type | Description | |--------|------|-------------| | version | INT64 | The table version number (monotonically increasing). | | timestamp | TIMESTAMP | The commit timestamp in milliseconds since epoch. | | operation | UTF8 | The type of operation (e.g., WRITE, MERGE, DELETE, OPTIMIZE, CREATE TABLE). | | operationParameters | UTF8 | JSON object with operation-specific parameters (e.g., predicate, partitionBy, mode). | | operationMetrics | UTF8 | JSON object with operation metrics (e.g., numOutputRows, numAddedFiles, rewriteTimeMs). | | userName | UTF8 | The user or principal that performed the operation, if recorded. | | engineInfo | UTF8 | Identifier of the engine that wrote the commit (e.g., "Delta-Forge/x.y.z"). | | numFiles | INT64 | Total number of active data files after the commit. | | sizeInBytes | INT64 | Total size of active data files in bytes after the commit. | | filesAdded | INT64 | Number of data files added by this commit. | | filesRemoved | INT64 | Number of data files removed by this commit. | | bytesAdded | INT64 | Total bytes of data files added by this commit. | | bytesRemoved | INT64 | Total bytes of data files removed by this commit. | | isBlindAppend | UTF8 | "true" if the operation only added data without reading existing files. | | isolationLevel | UTF8 | The transaction isolation level (e.g., Serializable, WriteSerializable). | When LIMIT is specified, only the N most recent entries are returned. ## Compatibility DESCRIBE HISTORY follows the same syntax as the Delta Lake DESCRIBE HISTORY command. The output columns are extended with file-level delta metrics (filesAdded, filesRemoved, bytesAdded, bytesRemoved) for a more complete view of each commit's impact.

Parameters

Name	Type	Description
`table`		Specifies the name or path of the Delta table whose history to retrieve. The table must be registered in the session via CREATE DELTA TABLE or OPEN DELTA TABLE. Fully qualified names (zone.schema.table) are supported.
`limit`		Maximum number of history entries to return.

Examples

-- Show full version history
DESCRIBE HISTORY warehouse.sales.orders;

-- Show the 10 most recent versions
DESCRIBE HISTORY warehouse.sales.orders LIMIT 10;

-- Inspect history of a partitioned table
DESCRIBE HISTORY gold.analytics.daily_revenue LIMIT 5;

-- Check history after a maintenance operation
DESCRIBE HISTORY warehouse.inventory.products LIMIT 3;

Pitfalls

History entries are only available for commits that have not been removed by log cleanup. Delta tables with short log retention (configured via delta.logRetentionDuration) may not expose older versions.
The operationParameters and operationMetrics columns contain JSON strings. Use your client's JSON parsing capabilities to extract specific values from these fields.
Without LIMIT, the command reads the entire transaction log history. For tables with thousands of versions, this can be slow and produce large result sets. Use LIMIT to restrict output for interactive exploration.