07 · Tables A→ZK · Maintain & tune performance
A maintenance cadence that scales
How often to optimize and vacuum so tables stay fast without wasting effort.
Maintenance is two periodic chores - optimize then vacuum - run often enough to keep reads fast, not so often that you waste effort or shrink your recovery window.
The standard loop
profile_table- current row count / shape.optimize_table- compact small files.vacuum_table(dry_run=true)- preview deletions.- Review file count + space savings.
vacuum_table(dry_run=false)- execute.get_table_history- confirm both ran.
Order matters: optimize first, then vacuum.
How often
| Table activity | Optimize | Vacuum |
|---|---|---|
| Frequent small writes | after each burst of writes | periodically (weekly), retention ≥ 168h |
| Steady/batch loads | after the batch | weekly/monthly |
| Rarely written | only if reads slow | rarely |
| Tiny (< ~1000 rows) | skip - negligible benefit | rarely |
Good to know
Check
get_table_history for
the last OPTIMIZE to avoid redundant runs. Don't optimize after every write -
batch writes, then optimize.Keep the recovery window in mind
Vacuum's retention_hours is your time-travel depth. Don't drop it below 168h
(7 days) just to reclaim a little space - see
Vacuum cuts time-travel.