Sign up

How to Time-Travel (Query Historical Data)

Open inAnthropic

What you'll achieve

By the end of this guide, you will know how to query your database at any historical commit, compare points in time, and restore previous states.

Time-travel in TerminusDB lets you query the database as it was at any point in history — without modifying anything. Because every write creates an immutable commit, you can "go back in time" to see the exact state of your data at any previous commit. No backups, no log replay, no special configuration.

How it works

TerminusDB stores data as immutable delta layers. When you time-travel, you read a snapshot frozen at that commit — the current database stays unchanged. This is read-only; you cannot accidentally modify history.

Prerequisites

  • TerminusDB running on localhost:6363
  • A database with some commit history. Examples use admin/mydb.

1. Get the commit history

View the commit log to find the commit you want to travel to.

HTTP API

curl -u admin:root "http://localhost:6363/api/log/admin/mydb/local/branch/main?count=5"

Expected response:

Example: JSON
[
  {
    "@id": "commit/abc123def456",
    "author": "alice@example.com",
    "message": "Update Widget price to 14.99",
    "timestamp": "2026-04-30T14:22:01.000Z",
    "identifier": "abc123def456"
  },
  {
    "@id": "commit/789xyz012345",
    "author": "alice@example.com",
    "message": "Add Widget product",
    "timestamp": "2026-04-29T10:15:30.000Z",
    "identifier": "789xyz012345"
  },
  {
    "@id": "commit/initial000001",
    "author": "admin",
    "message": "Initial schema",
    "timestamp": "2026-04-28T09:00:00.000Z",
    "identifier": "initial000001"
  }
]

Each commit has an identifier that you use for time-travel queries.

TypeScript

Example: TypeScript
import TerminusClient from "@terminusdb/terminusdb-client";

const client = new TerminusClient.WOQLClient("http://localhost:6363", {
  user: "admin",
  key: "root",
  organization: "admin",
  db: "mydb",
});

const log = await client.getCommitHistory({ count: 5 });
for (const commit of log) {
  console.log(`${commit.identifier} — ${commit.author}: ${commit.message}`);
}

Python

Example: Python
from terminusdb_client import Client

client = Client("http://localhost:6363")
client.connect(user="admin", key="root", db="mydb")

log = client.get_commit_history(count=5)
for commit in log:
    print(f"{commit['identifier']} — {commit['author']}: {commit['message']}")

2. Query data at a specific commit

Replace the branch path with a commit path to see the database at that exact moment.

HTTP API

# Query all Product documents as they were at commit 789xyz012345
curl -u admin:root "http://localhost:6363/api/document/admin/mydb/local/commit/789xyz012345?type=Product&as_list=true"

Expected response:

Example: JSON
[
  {"@id": "Product/Widget", "@type": "Product", "name": "Widget", "price": 9.99}
]

Note: the price is 9.99 (the value at that commit), not 14.99 (the current value). You are looking at a frozen snapshot.

TypeScript

Example: TypeScript
// Query at a specific commit
const historicalDocs = await client.getDocument({
  type: "Product",
  as_list: true,
  commit: "789xyz012345"
});
console.log(historicalDocs);
// [{name: "Widget", price: 9.99}] — the value at that point in time

Python

Example: Python
# Query at a specific commit
docs = client.get_all_documents(commit="789xyz012345")
for doc in docs:
    print(doc)
# {"name": "Widget", "price": 9.99} — the value at that point in time

3. Compare two points in time

Use diff to see exactly what changed between any two commits:

HTTP API

curl -u admin:root -X POST http://localhost:6363/api/diff/admin/mydb \
  -H "Content-Type: application/json" \
  -d '{
    "before_data_version": "admin/mydb/local/commit/789xyz012345",
    "after_data_version": "admin/mydb/local/commit/abc123def456"
  }'

Expected response:

Example: JSON
[
  {
    "@id": "terminusdb:///data/Product/Widget",
    "price": {"@op": "SwapValue", "@before": 9.99, "@after": 14.99}
  }
]

This shows you exactly what changed between those two commits — in this case, the Widget price went from 9.99 to 14.99.

4. Query a specific document's history

To see how a single document evolved over time, query it at successive commits:

HTTP API

# Get the document at the current state
curl -u admin:root "http://localhost:6363/api/document/admin/mydb/local/branch/main?id=terminusdb:///data/Product/Widget"

# Get the same document at a previous commit
curl -u admin:root "http://localhost:6363/api/document/admin/mydb/local/commit/789xyz012345?id=terminusdb:///data/Product/Widget"

Compare the responses to see how the document changed over time.

5. Restore a document to a previous state

If you want to revert a document to its historical value, read it from the commit and write it back to the current branch:

HTTP API

# 1. Read the document at the historical commit
curl -u admin:root "http://localhost:6363/api/document/admin/mydb/local/commit/789xyz012345?id=terminusdb:///data/Product/Widget"
# Response: {"@id": "Product/Widget", "@type": "Product", "name": "Widget", "price": 9.99}

# 2. Write it back to main (this creates a new commit — history is preserved)
curl -u admin:root -X PUT \
  "http://localhost:6363/api/document/admin/mydb/local/branch/main?author=alice&message=Restore+Widget+to+original+price" \
  -H "Content-Type: application/json" \
  -d '{"@id": "Product/Widget", "@type": "Product", "name": "Widget", "price": 9.99}'

Expected response:

Example: JSON
["terminusdb:///data/Product/Widget"]

This does not erase history — it creates a new commit that sets the document back to its previous value. TerminusDB preserves the full history of changes.

TypeScript

Example: TypeScript
// Read from historical commit
const historical = await client.getDocument({
  id: "terminusdb:///data/Product/Widget",
  commit: "789xyz012345"
});

// Write back to current branch
client.checkout("main");
await client.updateDocument(historical, {
  author: "alice",
  message: "Restore Widget to original price"
});

Python

Example: Python
# Read from historical commit
historical = client.get_document("terminusdb:///data/Product/Widget", commit="789xyz012345")

# Write back to current branch
client.checkout("main")
client.update_document(historical, commit_msg="Restore Widget to original price")

Complete workflow: audit and restore

# 1. Get recent commit history
curl -u admin:root "http://localhost:6363/api/log/admin/mydb/local/branch/main?count=10"

# 2. Find the commit before the unwanted change (e.g., 789xyz012345)

# 3. See what the database looked like at that commit
curl -u admin:root "http://localhost:6363/api/document/admin/mydb/local/commit/789xyz012345?type=Product&as_list=true"

# 4. Diff current state vs that historical commit
curl -u admin:root -X POST http://localhost:6363/api/diff/admin/mydb \
  -H "Content-Type: application/json" \
  -d '{"before_data_version": "admin/mydb/local/commit/789xyz012345", "after_data_version": "main"}'

# 5. If you want to restore to that state, use reset (see How to Undo Changes)
#    or selectively restore individual documents as shown above

Next steps

Open inAnthropic
Report issue

Was this helpful?