Snapshots & Backups
Create point-in-time snapshots, list them, and restore from them.
What you'll learn
- ✓POST /v1/snapshots — name, description
- ✓GET /v1/snapshots — list all snapshots with size and ts_hlc
- ✓POST /v1/snapshots/:id/restore — replace current data with snapshot
- ✓Restore warning: records written after snapshot are lost
- ✓Best practice: maintenance mode before restore, checkpoint before snapshot
Create a snapshot. Write 5 more records. Restore the snapshot. Confirm the 5 records are gone.
What you'll learn
Create named snapshots as HLC bookmarks, list them, and use them for time-travel queries.
What snapshots are (and aren't)
A SapixDB snapshot is a named pointer to an HLC timestamp — not a copy of your data. Snapshots make it easy to go back to a specific moment using as_of queries. They do not restore data, they do not take any disk space beyond the bookmark, and there is no "roll back" operation.
Because records are immutable by design, you can always query the database as it was at any past instant — snapshots just give those instants a human-readable name.
Create a snapshot
curl -s -X POST http://localhost:7475/v1/snapshots \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"name": "pre-migration-2026-08-06", "description": "before schema change"}' \
| python3 -m json.toolResponse:
`json
{
"name": "pre-migration-2026-08-06",
"description": "before schema change",
"timestamp_hlc": 1754481600000000,
"timestamp_ms": 1754481600000,
"created_by": "spx_root_...",
"created_at_ms": 1754481600000
}
`
timestamp_hlc is the HLC value you pass to as_of queries. timestamp_ms is timestamp_hlc >> 16 (unix milliseconds).
List snapshots
curl -s http://localhost:7475/v1/snapshots \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolUse a snapshot for time travel
`bash
# Retrieve the snapshot to get its timestamp_hlc
curl -s http://localhost:7475/v1/snapshots/pre-migration-2026-08-06 \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"
# Query any agent as of that moment
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"type": "as_of", "timestamp_hlc": 1754481600000000, "limit": 100}' \
| python3 -m json.tool
`
Best practice naming script
#!/bin/bash
DATE=$(date +%Y-%m-%d)
curl -s -X POST http://localhost:7475/v1/snapshots \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SAPIX_ROOT_KEY" \
-d "{\"name\": \"daily-$DATE\", \"description\": \"Automated daily bookmark\"}"Run this daily via system cron: 0 2 * * * /path/to/snapshot.sh
Challenge
Create a snapshot, write 5 more records, then use the snapshot's timestamp_hlc in an as_of query. Confirm the query returns state from before those 5 records.
---