dodil data table — maintenance

Operational table maintenance. Three commands — compact drains the write-ahead log into Delta on demand, optimize packs small Delta files, vacuum reclaims space past retention. The plane runs the WAL → Delta drain automatically in the background; you reach for these 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

Force the write-ahead log to drain into Delta now. No flags — there is no --batch-size. Call it manually for:

• After bulk writes — materialize rows in Delta immediately for analytical reads
• Before maintenance — compact → optimize is the canonical post-batch sequence
• Tests / e2e — drain the WAL so a subsequent read takes the analytical fast path deterministically

dodil data table compact events -b kb-prod

Reading the response:

wal_unique_keys < wal_entries_processed is normal and healthy — the compactor dedupes repeated writes to the same key (newest wins) before the Delta MERGE. Full response contract: Maintenance → Compact.

A drained WAL is also what lets a read take the cheap path: the frontier check can only prove eventual ≡ strong when the backlog is empty. See Core Concepts.

dodil data table optimize

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

Two modes:

• Bin-pack (default) — coalesce small Delta 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.

There is no --target-file-size-mb flag on the CLI; the target file size is a server-side default. To set it explicitly, use the OptimizeTable RPC.

# 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 Delta file versions older than the retention window. Destructive — vacuumed files are gone, and the Delta versions they backed can no longer be read or restored.

# 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, SELECT … VERSION AS OF and RESTORE … TO VERSION AS OF 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:

# Find a target version first
dodil data sql -b kb-prod "SELECT * FROM events VERSION AS OF 41 LIMIT 5"
 
# Then restore
dodil data sql -b kb-prod "RESTORE TABLE events TO VERSION AS OF 41"

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

• It destroys the tail. Restoring rolls the table back and wipes the WAL — un-drained writes after the target version are gone, not replayed.
• Indexes are not rolled back. Secondary and vector indexes keep their post-restore state and must be rebuilt.

Details: Maintenance → RESTORE.

Canonical post-batch sequence

# 1. Drain the WAL into Delta
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

See also

• Maintenance — API Reference — OptimizeTable · VacuumTable · Compact · RESTORE
• dodil data table — lifecycle — describe for the current schema
• dodil data table — data — what produces WAL entries in the first place
• Recipes → Time travel + Restore — the vacuum / restore interaction