Skip to main content

Time Travel

Time Travel offers the ability to query historical data. This allows to query the Delta Lake table as it was when a previous snapshot of the table was taken, even if the data has since been modified or deleted.

You can query a previous version of a Delta Lake table using either the snapshot version number or the timestamp of the transaction.

  • To query a specific snapshot by version, append the version number to the table name in the format: <table_name>@v<version_id>.

  • To query a snapshot by timestamp, append the timestamp in the format: <table_name>@t<version_timestamp>.


Syntax​

-- To query a specific snapshot by version:
SELECT * FROM <catalog_name>.<schema_name>."<table_name>@v<version_id>"

-- To query a snapshot by timestamp:
SELECT * FROM <catalog_name>.<schema_name>."<table_name>@t<version_timestamp>"

Parameters​

  • <catalog_name>

    The name of the external catalog.

  • <schema_name>

    The name of the external schema.

  • <table_name>

    The name of the table.

Usage notes​

We recommend that you first query the $history metadata table corresponding to your Delta Lake table to check the valid historical versions.

For example, run the following query:

SELECT version, operation FROM example.testdb."customer_orders$history" ORDER BY version DESC;

This query checks the history of operations performed on the customer_orders table, with the latest operations displayed at the top.

For more information about the $history metadata table, see Metadata Tables.

Examples​

Retrieve all data from the Delta Lake table test-data as it existed in version 1:

SELECT * FROM catalog_time_travel.time_travel."test-data@v1";

Retrieve all data from the test-data table as it appeared at 2024-09-12 07:46:20:

SELECT * FROM catalog_time_travel.time_travel."test-data@t2024-09-12 07:46:20";