Overview
The change history of a data table answers the question of who made what changes to the table and when. After you open the details page of any table in Catalog, the Change History Tab displays all data and DDL operation records of the table in reverse chronological order by version, and supports filtering by user, operation type, and time range. DataBuddy also supports querying the change history of a table directly in Spark SQL through DESCRIBE HISTORY, facilitating programmatic auditing in SQL / Notebook pipelines.
Applicable scenarios:
Investigate why the table data was modified, who modified it, and when it was modified.
Verify whether recent DDL changes (such as adding columns, dropping partitions, or rewriting table structures) meet expectations.
Locate the specific version numbers and commit records during incident reviews, compliance audits, and version tracing.
Prerequisites
The current account can log in to the workspace and has Read or higher permissions on the target Catalog → Schema → Table.
The Catalog containing the target table is bound to a compute engine that supports reading table history. For details, see Limitations. When viewing the change history on the Catalog table details page, you need to first select an available compute resource to pull the historical data.
Use Limits
Limit | Description |
Engine Dependency | Reading table change history depends on the underlying Catalog implementation. Supported operation types and field ranges may vary by engine. |
Number of Records | The page displays up to the first 100 change records. To view more records, use the DESCRIBE HISTORY query in SQL. |
Display Fields | Currently displayed fields include version number, timestamp, user ID, username, operation, and operation parameters. More fields will be added gradually, such as job, Notebook, Cluster ID, version number, transaction isolation level, blind append or not, operation metrics, user-defined remarks, and engine information. |
Computing Resource | You must select a compute resource before going to the Change History Tab. If the compute resource is not started, it will be started first, and historical data cannot be read during startup. |
Operation Steps
Step 1: Going to the Table Details Page
2. Switch to the target region and Workspace at the top.
3. Select Data Catalog in the left sidebar.
4. Expand Catalog > Schema in order, and click the target table name to go to the table details page.
Step 2: Selecting Compute Resources
1. On the table details page, switch to the Change History Tab.
2. If the current compute resource is not started, select an available compute resource in the selection box as prompted on the page.
The compute resource selection box supports search.
Resource statuses are indicated by colors and icons: green indicates Running, gray indicates Pending Start, and a circle indicates Starting. Hover over a resource to view its full name and status description.
1. After selection, the system prompts The compute resource is starting... For more information, go to Compute Resources. You can click the resource name to go to the Compute Resources page to view the startup details.
2. After the startup is complete, the system prompts The compute resource has started. For more information, go to Compute Resources. You can now view the change history.
Tip
The compute resource selection has a memory feature: when you open the Change History Tab again, your previous selection is automatically retained.
Step 3: Viewing Change History
Change history is displayed in a table in reverse version order. Common fields are as follows:
Field | Description |
Version | Version numbers of the table, sorted in descending order with the latest version at the top. |
Time | Timestamp of the version submission, displayed with the latest time first. |
Change Type | Operation type of the change, such as INSERT, UPDATE, DELETE, MERGE, CREATE TABLE, DROP TABLE, TRUNCATE, RESTORE, and ALTER TABLE. |
User uin | Account ID and display name that triggered the change. |
Operation / Operation Parameters | Specific operations and parameters recorded by the engine. |
Operation Steps | Detailed description. Click the triangle to expand and view. |
The table supports horizontal scrolling. Swipe right to view all fields. When there are many change records, a message appears at the bottom of the page: A maximum of the first 100 change records are displayed. If you need more change records, go to the SQL query page and use DESCRIBE HISTORY to query them.
Step 4: Filtering by User or Operation Type
1. Filter above the table:
User: All Users by default. You can select one or more users to filter.
1. To filter by time, select a date in the time range control.
2. After you modify the filter criteria, the table refreshes automatically. You can use the browser back button or select All Users / All Operations again to restore the default view.
Step 5: Querying Table Change History in SQL
To programmatically read the change history in SQL / Notebook, execute the following in a query session bound to the corresponding engine:
DESCRIBE HISTORY databricks_test.logantest.`customer_info`;
Replace databricks_test.logantest.customer_info with your catalog.schema.table path. If the table name contains Chinese characters, spaces, or reserved words, enclose it in backticks. The returned results match the fields on the table details page. You can further filter them using clauses such as WHERE, ORDER BY, and LIMIT.
Tip
The specific support scope and returned fields of DESCRIBE HISTORY are determined by the underlying engine. Confirm that the engine used by the session supports this syntax first.
FAQs
Q: Why Can't I See a Write or DDL Operation in the Change History?
A: Confirm the following in order:
1. Whether the current Catalog / engine supports recording this type of operation. Note that some engines do not record all DDL operations.
2. Whether the results are truncated by the first 100 records limit. If the results are truncated, use DESCRIBE HISTORY to query instead.
3. Whether the operation occurred outside the selected time range (up to 30 days).
Q: Why Does the Change History Tab Keep Showing "Select Compute Resources"?
A: This indicates that the current session has no available compute resources. Start an available resource on the Compute Resources page first, or select a resource in the Running or Starting state from the selection box.
Q: Can I View the Specific Data Differences of a Change?
A: The current version displays only metadata such as the version number, operation, operation parameters, and change log. To view row-level differences, you need to run comparison queries between different versions using SQL, for example, by leveraging the engine's native version access syntax.
Q: Can I Roll Back to a Historical Version from the Change History?
A: The current version does not provide a page-based rollback operation. To perform a rollback, find the target version based on the DESCRIBE HISTORY output, and then complete the rollback in SQL using the engine-supported rollback or RESTORE syntax.
References
Column-level permission control