Skip to Content
We are live but in Staging 🎉
Data EnginesSQLCLIdodil data table (maintenance)

dodil data table — maintenance

Operational table maintenance. Three commands — compact applies pending writes to the table’s storage on demand, optimize packs small storage files, vacuum reclaims space past retention. The engine does all three on its own schedule; you reach for them for explicit packing, space reclamation and post-batch sequencing.

Persistent flag on the group: --bucket / -b.

Restore is SQL, not a command. There is no dodil data table restore and no Restore RPC — run RESTORE TABLE t TO VERSION AS OF n through dodil data sql. There is no History RPC or command either. See Recipes → Time travel + Restore.

dodil data table compact

dodil data table compact [name] -b BUCKET

Apply pending writes to the table’s storage now instead of on the next background pass. No flags. Call it manually for:

  • After bulk writes — so analytical scans read packed storage instead of merging a large backlog
  • Before maintenance — compact → optimize is the canonical post-batch sequence
  • Tests / e2e — for a deterministic storage state
dodil data table compact events -b kb-prod

Reading the response:

FieldMeaning
wal_entries_processedPending writes applied this pass
wal_unique_keysDistinct primary keys after newest-per-key dedup
drained_high_ulidThe highest write applied

wal_unique_keys < wal_entries_processed is normal — repeated writes to the same key collapse to the newest. Compaction never changes what a read returns; every committed write is already visible. Full response contract: Tables & maintenance → Compact.

dodil data table optimize

dodil data table optimize [name] -b BUCKET [--z-order-column COL ...]

Two modes:

  • Bin-pack (default) — coalesce small storage files per partition.
  • Z-order — set --z-order-column to rewrite files clustered by those columns, improving read locality for queries that filter on them.
FlagTypeDefaultDescription
--z-order-columnstring list (repeat)[]Columns to cluster by. Any value switches the mode to z-order.

There is no --target-file-size-mb flag; the target file size is a server-side default and is not caller-tunable on the OptimizeTable RPC either.

# Bin-pack
dodil data table optimize events -b kb-prod
 
# Z-order for queries that filter on (event_type, user_id)
dodil data table optimize events -b kb-prod \
  --z-order-column event_type --z-order-column user_id

When to call: after large bulk writes, nightly batches, or a migration. Routinely-compacted tables stay well-packed on their own.

dodil data table vacuum

dodil data table vacuum [name] -b BUCKET [--retention-hours N] [--dry-run]

Permanently delete storage files older than the retention window. Destructive — vacuumed files are gone, and the table versions they backed can no longer be read or restored.

FlagTypeDefaultDescription
--retention-hoursint168 (7 days)Retention window
--dry-runboolfalsePreview the files that would be deleted
# ALWAYS dry-run first
dodil data table vacuum events -b kb-prod --dry-run -o json
 
# Real run, after reviewing
dodil data table vacuum events -b kb-prod
 
# Longer retention
dodil data table vacuum events -b kb-prod --retention-hours 720   # 30 days

168 hours is both the default and the floor, and there is no bypass. A shorter --retention-hours is clamped up to 168. There is no --disable-retention-check flag — it never existed on this CLI. If you need files gone sooner than the floor, you cannot get there with vacuum.

Vacuum destroys time travel. Once you vacuum past version N, RESTORE … TO VERSION AS OF and GetRow … as_of_version for any version below N stop working — the files they referenced are deleted. Check what you still need before you run it. The safe sequencing is documented at Recipes → Time travel & restore.

Restore — the SQL verb

Restore is not one of these commands. Run it as SQL:

# The version to target is the one you recorded before the risky change
# (any DDL response, or TableStats.delta_version from GetDatabaseStats).
dodil data sql -b kb-prod "RESTORE TABLE events TO VERSION AS OF 41"
 
# Or by wall-clock instant (offset required)
dodil data sql -b kb-prod "RESTORE TABLE events TO TIMESTAMP AS OF '2026-09-17T08:00:00Z'"

Two things about restore that surprise people, and both are worth reading before you run it:

  • It destroys writes made after the target version. Committed and pending alike — they are gone, not replayed.
  • Indexes are not rolled back. Secondary and vector indexes are reconciled afterwards by revalidation and backfill; the statement warns when the table has any.

Details: Schema changes → RESTORE.

Canonical post-batch sequence

# 1. Apply pending writes to storage
dodil data table compact events -b kb-prod
 
# 2. Bin-pack the resulting small files
dodil data table optimize events -b kb-prod
 
# 3. (Periodically) expire old versions — always preview first
dodil data table vacuum events -b kb-prod --dry-run
dodil data table vacuum events -b kb-prod
dodil data table (data)Overview