optimize
Compact Lance fragments across every table in the graph.
optimize runs Lance's compact_files() on every node and edge table. It
rewrites many small fragments into fewer large ones, lowering read latency
and reducing per-scan overhead. It is non-destructive. Older fragments
remain reachable via earlier manifests until omnigraph cleanup reclaims
them.
Run optimize periodically against graphs that take frequent small writes.
It does not change any data; it only reorganizes storage.
Usage
omnigraph optimize <path> [options]Arguments
| Argument | Required | Description |
|---|---|---|
path | yes | Graph URI (local path or s3://); required unless resolved from --target / --config |
Options
| Option | Required | Default | Description |
|---|---|---|---|
--target | no | — | Named graph from omnigraph.yaml |
--config | no | — | Path to an omnigraph.yaml |
--json | no | — | Output stats as JSON |
The optimizer parallelizes across tables. The concurrency ceiling is set by
OMNIGRAPH_MAINTENANCE_CONCURRENCY (default 8).
Output
For each table the command returns a TableOptimizeStats record:
| Field | Description |
|---|---|
table_key | The node or edge type whose storage was optimized |
fragments_removed | Number of small fragments compacted away |
fragments_added | Number of new large fragments written |
committed | Whether a new manifest was committed (false if no work was needed) |
Example
omnigraph optimize ./graph.omni --jsonPairing with cleanup
optimize makes new compacted fragments without freeing the old ones. Old
fragments stay live until omnigraph cleanup removes their backing
manifests. The typical cadence is:
omnigraph optimize ./graph.omni
omnigraph cleanup ./graph.omni --keep 10 --confirm