Skip to content

memory: the table-handle cache holds 64 superseded manifests of a hot table, so live memory grows with fragment count × 64 #859

Open

Description

@ragnorc

Summary

TableHandleCache (crates/omnigraph-core/src/handle_cache.rs) holds up to 64 open Dataset handles keyed by (table_path, table_branch, version, staged_version, e_tag). Every write opens its base table through it (resolve_pinned_for_write → get_or_open in crates/omnigraph/src/db/omnigraph/promotion.rs), and every live-branch read does the same (SnapshotReadCaches in crates/omnigraph-catalog/src/lib.rs). Only a refresh or branch switch clears it.

Under steady writes each commit is a new key, so the cache fills with the newest 64 versions of the hot table. Each handle owns its own decoded Lance manifest, and a manifest lists every fragment. Live memory therefore grows as about 64 × fragment count × ~0.9 KB.

The cap's doc comment says a handle "holds only Arcs (object store + manifest), never table data, so this is cheap". That holds only while the manifest is small; its size is linear in fragment count.

Measurement

Setup:

  • the concurrent-writes bench scenario, one writer, file://, a release build of 97f293e8, 64 seed rows;
  • a 5-second warmup and a 90-second window, two runs per arm;
  • live heap read with macOS heap <pid> at the end of the window.

The two arms differ only in TABLE_HANDLE_CACHE_CAP.

TABLE_HANDLE_CACHE_CAP commits (fragments) live heap 384-byte blocks peak RSS commits/s p50
64 (current) 2,829 / 2,915 197 MB / 197 MB 186,145 / 193,078 376 / 435 MB 25 / 26 38.3 / 36.7 ms
4 2,811 / 2,887 40 MB / 40 MB 21,931 / 22,651 234 / 263 MB 26 / 26 37.0 / 37.5 ms

Without compaction, the curve looks quadratic in commit count. Each commit adds a fragment and a new cached version, and each of the 64 cached versions holds about as many fragments as the table has. One writer reached 918 MB peak RSS after 3,380 commits (cap 64).

Extrapolation: one hot table at 10,000 fragments makes the 64 entries about 590 MB. There is one cache per graph handle, so this repeats for every graph a server opens.

Why it matters

  • Invariant 11. Hot-path memory must scale with the working set, not accumulated history. Superseded versions are outside the working set:

    • the next write stages on the newest pin;
    • a live read opens the current snapshot;
    • a reader still holding an older Dataset keeps its own clone.

    Keys are version-exact, so evicting an entry costs at most one reopen and never changes a result.

  • Maintenance dependency. Only an operator running optimize bounds the fragment count. The cache's memory should not depend on that.

  • server: data-plane Lance session caches use Lance defaults (6 GiB + 1 GiB per graph) — long-lived server grows until OOM-killed #702. This is a likely contributor to the climb reported there. A long-lived server with sync writers grows with commit count, and a restart resets it.

Proposed direction

Bound the cache by the working set instead of version count:

  1. Keep only the newest version, or the newest two, per (table_path, table_branch). Evict the superseded entry when a newer version of the same cell is inserted.
  2. Keep the overall LRU cap on distinct cells.
  3. Alternatively, weigh entries by fragment count.

Snapshot-id reads already bypass the cache. #818 (hold the version a write committed) inserts the same keys and keeps the same bound, so the change applies to it as well.

Acceptance:

  • Under a sustained single-table write load, the held-handle count per (table, branch) stays at the chosen bound regardless of commit count.
  • warm_read_cost.rs and write_cost.rs request counts are unchanged.

Reproduce

Build the scenarios bench at 97f293e8, then again with TABLE_HANDLE_CACHE_CAP set to 4, and run each:

RUSTFLAGS= cargo bench --locked -p omnigraph-engine --bench scenarios --no-run
<scenarios binary> --scenario concurrent-writes --writers 1 --write-branches 1 \
  --duration-secs 90 --warmup-secs 5 --rows 64 --dims 8 --runs 1

While the child process runs, heap <child pid> | grep 'nodes (' gives the live heap.

Activity

  1. added
    needs-triageAwaiting maintainer triage
    performanceCorrect result, wrong cost: work scales with the table, not with the delta or the query
    on Oct 3, 2026
  2. added
    acceptedTriaged and validated; open for a PR
    P-highHigh priority
    and removed
    needs-triageAwaiting maintainer triage
    on Oct 4, 2026
  3. ragnorc commented on Oct 17, 2026

    @ragnorc
    ContributorAuthor

    Reproduction and assessment

    Summary. TableHandleCache keeps up to 64 open Dataset handles. Each commit to a table makes a new cache key, so under steady writes the cache fills with the newest 64 versions of the hot table. Each handle owns a full decoded Lance manifest, and a manifest lists every fragment. Memory therefore grows as about 64 × fragment count × 0.9 KB. Only the newest version is in the working set. Evicting an older entry costs at most one reopen and cannot change a result.

    Verdict: reproduced on main at 4d7536d68b1db6da34bf9cff22a90d9fdd77bed4, with the same mechanism and the same cost per fragment. The absolute totals are lower than in the report because this VM commits more slowly.

    Environment, and differences from the report

    Report This run
    Commit 97f293e8 4d7536d6 (handle_cache.rs is byte-identical between the two)
    OS macOS Ubuntu Linux, glibc 2.39, 4 vCPU, 15 GB
    Live heap heap <pid> glibc mallinfo2() (uordblks + hblkhd), read in-process at the end of the window
    RSS wait4 peak /proc/self/status VmRSS / VmHWM at the end of the window
    Bench scenarios --scenario concurrent-writes That bench is disabled on main (#894 moved it to benchmarks/deferred/). I used a scratch harness with the same workload: the same Chunk { slug @key, embedding: Vector(8) } schema, 64 seed rows, one closed-loop writer running Session::mutate insert on main, a 5 s warmup and a 90 s window. It has no I/O probes and no readback verification.
    Cap toggle two builds one release build (RUSTFLAGS=), with the cap read from an environment variable in the scratch build
    Throughput 25–26 commits/s about 15 commits/s, so about 1,650 commits instead of about 2,850

    Proof 1: minimal failing tests on main

    I added two tests in existing test owners. Neither is pushed. A test-only accessor, TableHandleCache::held(), returns each key with its manifest's fragment count.

    • omnigraph-core, the in-file tests in handle_cache.rs. This test creates one Lance table with 80 versions (version v has v fragments) and calls get_or_open for each version, as a writer does with its base pin.
    • omnigraph-engine, the in-source tests in runtime_cache.rs. This test runs 80 single-row Session::mutate inserts on main, then inspects read_caches().handles.
    cargo test -p omnigraph-core --locked --lib superseded_versions_of_one_table_stay_held_issue_859 -- --nocapture
    issue 859: after 80 commits of one table the cache holds 64 versions of it, 3104 fragment entries in their manifests; the newest version alone lists 80
    assertion `left == right` failed: superseded versions of one (table, branch) cell stay held: 64 versions, 3104 fragment entries (newest lists 80)
      left: 64
     right: 1
    test result: FAILED. 0 passed; 1 failed
    
    cargo test -p omnigraph-engine --locked --lib single_writer_keeps_superseded_versions_of_the_hot_table_issue_859 -- --nocapture
    issue 859: nodes/0000000000000001-0000000000000003 None: 64 held versions (newest 80), 3040 fragment entries in their manifests
    after 80 commits the hot table holds 64 versions with 3040 fragment entries
    test result: FAILED. 0 passed; 1 failed
    

    The totals match the arithmetic for a sliding window of 64 versions (17..80 sums to 3,104; 16..79 sums to 3,040). The engine test is the end-to-end proof; the core test isolates the retention rule. Both can become the fix's regression tests by changing the assertion to the chosen bound.

    Test code (engine test; the core test has the same shape)
    // crates/omnigraph-core/src/handle_cache.rs (test-only accessor)
    #[cfg(any(test, feature = "test-util"))]
    impl TableHandleCache {
        pub async fn held(&self) -> Vec<(TableHandleKey, usize)> {
            let inner = self.inner.lock().await;
            inner.entries.entries.iter()
                .map(|(key, dataset)| (key.clone(), dataset.manifest().fragments.len()))
                .collect()
        }
    }
    
    // crates/omnigraph/src/runtime_cache.rs, mod tests
    #[tokio::test]
    async fn single_writer_keeps_superseded_versions_of_the_hot_table_issue_859() {
        const SCHEMA: &str = "node Chunk { slug: String @key }";
        const COMMITS: usize = 80;
        let dir = tempfile::tempdir().unwrap();
        let graph = Arc::new(crate::db::Omnigraph::init(dir.path().to_str().unwrap(), SCHEMA).await.unwrap());
        let session = crate::Session::from_defaults(Arc::clone(&graph),
            omnigraph_compiler::settings::SessionSettings::default());
        for seq in 0..COMMITS {
            session.mutate("main", "query put($slug: String) { insert Chunk { slug: $slug } }", "put",
                &HashMap::from([("slug".to_string(),
                    omnigraph_compiler::query::ast::Literal::String(format!("c{seq}")))])).await.unwrap();
        }
        // group held() by (table_path, table_branch); assert versions per cell <= bound
    }

    Proof 2: the bench-shaped workload in a release build

    RUSTFLAGS= cargo build --release --locked -p omnigraph-engine --example og859_concurrent_writes
    for cap in 64 4 64 4; do OG859_CAP=$cap target/release/examples/og859_concurrent_writes; done
    
    Cap Commits (total) Live heap at end RSS at end Held fragment entries Commits/s p50
    64 1,652 / 1,601 114.8 / 112.2 MB 255 / 261 MB 103,712 / 100,448 15.1 / 14.7 66.7 / 69.1 ms
    4 1,667 / 1,672 27.2 / 27.3 MB 174 / 170 MB 6,662 / 6,682 15.4 / 15.4 65.0 / 62.6 ms
    • Cost per fragment entry. The extra live heap divided by the extra fragment entries is (114.8 − 27.2) MB / 97,050 = 0.90 KB, and (112.2 − 27.3) MB / 93,766 = 0.91 KB. The report's figure is about 0.9 KB.
    • Lance session caches. Session::size_bytes() reads 9.5–10.0 MB in all four runs. The growth is not in Lance's caches.
    • Throughput. The two arms differ by less than the run-to-run noise. The 60 extra entries buy nothing for this workload.

    Root cause (code at 4d7536d)

    1. The key is version-exact. TableHandleKey includes version, staged_version and e_tag (handle_cache.rs L82-L91), so each commit makes a new key.
    2. Writes and reads insert through the cache. The write path opens its base pin with get_or_open (promotion.rs L90-L120). Live branch reads do the same (omnigraph-catalog/src/lib.rs L711-L740).
    3. Retention counts entries, not bytes. LruMap evicts only by entry count (L43-L52). The cap is 64, and its doc comment says a handle is "cheap" (L75-L80).
    4. Each version decodes the full fragment list. A Dataset holds manifest: Arc<Manifest> (lance dataset.rs L198), and Manifest holds fragments: Arc<Vec<Fragment>> (lance-table manifest.rs L55). Each version decodes its own full list, so 64 versions hold about 64 × F fragment records.
    5. Nothing clears the cache for a single writer. Only a refresh, a branch switch, a stale freshness probe on the bound branch, or a mutation reprepare clears it (omnigraph.rs L2208-L2217, L2470-L2485, mutation.rs L1117). A single writer's own publications never reach those paths, so a single writer is the worst case. With several writers, the reprepare path clears the cache as a side effect.
    6. The cache bypasses Lance's byte budget. Lance's own metadata cache already stores manifests by (version, e_tag) (get_manifest, L830) and weighs them by DeepSizeOf under a byte budget (lance-core cache/mod.rs L191). A strong Dataset clone in the handle cache keeps a manifest alive after Lance evicts it, so the handle cache is the holder that has no byte limit.
    7. The model it cites holds one handle per table. The doc comment names LanceDB's DatasetConsistencyWrapper as the model. That wrapper holds one Dataset per table and replaces it in update() after a write (rust/lancedb/src/table/dataset.rs). OmniGraph keeps 64.

    This breaks invariant 11: hot-path memory must scale with the working set, not with accumulated history.

    Recommended fix (correct by design)

    A. Replace the superseded handle at the publication door. After a successful publication, the writer knows the exact pin it staged on and the exact pin it published, for each table it moved. Hold the new handle and remove the base key: a replace, not an add. Do this once, where the publication completes, so every writer gets it: mutate, load, merge, schema apply, optimize and Blob writes. The cache then holds one version per table per graph branch in use, which is the working set. #818's hold_published becomes the insert half of this replace.

    Why not "keep the newest N per (table_path, table_branch)", as the issue proposes:

    • Graph branches stage detached commits on the same Lance dataset and native ref. Two graph branches that write one table therefore share table_branch = None but have different pins.
    • Detached version ids are random (lance io/commit.rs L1065), and version is a per-lineage counter. The cache cannot find a lineage from its key.
    • A "newest per cell" rule would therefore evict branch A's head whenever branch B writes, which adds one reopen per write and undoes perf(writes): hold the version a write committed in the read-handle cache #818's saving.
    • The publisher knows which pin it superseded; the cache does not.

    B. Add a byte backstop. Weigh each entry by its manifest size (fragment count, or Manifest::deep_size_of, as Lance does). Evict least-recently-used entries down to a budget, and always admit the newest entry. This limits the paths that A does not see:

    • reads of a branch that is not bound, written by another handle or process;
    • many branches at once;
    • live reads that hold an older pin.

    Weighing is O(F), but it runs only on a miss, which has already paid an O(F) decode.

    C. Update the tests and the doc comment. Remove the "cheap" claim from the doc comment. Keep the two tests above as issue_859 regressions that assert the bound. Keep the warm_read_cost.rs and write_cost.rs counts unchanged. If a labeled DST scenario gains a reopen (for example, after a fork that shares a base pin), update crates/omnigraph-dst/cost_table.txt and explain each changed line.

    Alternatives I set aside:

    • Lower the cap (for example to 4–8). This is a patch, and memory still scales with F × cap. A graph with more live tables × branches than the cap would reopen on every read, so the right cap would depend on the schema size. It is acceptable only as a stopgap.
    • Byte budget only (B without A). Memory is bounded, but the steady state fills the budget with superseded history. It is a valid first step.
    • Remove TableHandleCache and rely on Lance's session cache. A pinned open whose manifest size is unknown skips Lance's cache (L836-L840) and costs I/O. That breaks the zero-open contract in warm_read_cost.rs.
    • A version-free key refreshed in place, as LanceDB does. A concurrent reader at the previous pin would lose its coherent snapshot (invariant 3).

    Tradeoffs and long-term cost. A adds a small amount of code in one place, tied to the publication door that already exists. Its residual cost is that a concurrent reader at the base pin, or a fresh fork that shares that pin, pays one reopen. B adds one weight function and one internal budget constant. The design gives up a small amount of efficiency (an occasional reopen) for robustness (memory that does not grow with commit count). Correctness does not change, because keys stay version-exact and the cache stays derived state (invariant 7).

    Related open PRs and issues

    Lance upstream assessment

    • Released versions do not fix this. OmniGraph pins 11.0.0. Since then, Lance has released v12.0.0 and v13.0.0 (latest), and v14.0.0-beta.19 is out. In v13.0.0 and v14.0.0-beta.19, Manifest still holds fragments: Arc<Vec<Fragment>>, so each version still decodes its full fragment list. A Lance bump does not fix this issue.

    • Fragment metadata trees may help later.

      • lance#7941 (open) proposes hierarchical, independently loadable fragment catalogs, and names memory growth with fragment count.
      • lance#9060 (merged) defines a fragment metadata tree format whose immutable leaves can be reused across versions.
      • lance#9178 (draft) is a prototype with lazy metadata reads, enabled per table with lance.manifest.layout=tree.
      • lance#9726 (open) implements the tree in lance-table only. Flat manifests stay the default, and native Dataset still refuses the flag.

      If versions come to share decoded leaves in memory, the cost per held version could fall. But the feature is experimental and opt-in at table creation, and adopting it would be a storage-format decision for OmniGraph that needs an RFC and compatibility evidence. It does not replace a retention bound.

    • lance#10037 (open): a written manifest keeps its encoded fragment bytes. This may increase memory for held committed handles (see perf(writes): hold the version a write committed in the read-handle cache #818 above).

    • Lance's metadata cache is the model for B. It is already byte-weighed with DeepSizeOf.

    Limitations

    • I measured on Linux with glibc mallinfo2, not macOS heap. The absolute values are not directly comparable to the report; the ratio and the cost per fragment are.
    • I used a scratch harness, not the original bench, which is disabled on main. It has no I/O probes. RSS is read at the end of the window, not as a wait4 peak. I ran two runs per arm, closed loop, on file:// only.
    • I did not measure the 10,000-fragment extrapolation, a server with many graphs, or S3.
    • I did not build perf(writes): hold the version a write committed in the read-handle cache #818, because it has merge conflicts with main. My assessment of it comes from its diff.
    • The tests and harness are not pushed. They exist only as local scratch changes.
  4. blarghmatey commented on Nov 5, 2026

    @blarghmatey
    Contributor

    A production data point for this, on S3 and with many graphs on one server, which the assessment above lists as unmeasured.

    We run omnigraph-server v0.14.0 (release binary, glibc, single replica) against S3 in a 2 GiB container. It was OOMKilled four times in 14 days (11-02 14:41Z, 11-03 14:37Z, 11-04 14:17Z, 11-05 12:18Z). The pod restarts nightly, and memory sits at about 100-280 MiB until one client starts a write session. That client commits about once every 3.5s for hours, almost entirely to one long-lived branch of one graph: 6,736 commits to that branch over 11-02..11-04, with its manifest at version 3,831 by 11-04.

    On 11-04 the working set went from 125 MiB at 07:00Z to 1,521 MiB at 09:30Z and 1,828 MiB at 10:00Z, then stayed between 1,829 and 1,875 MiB until the kill while the same writes continued (about 2,000 more commits). It was anonymous memory (container RSS 1,816-1,860 MiB, page cache 4-8 MiB). Each kill came when another client's writes landed on top of the plateau. On a day when a different client made 1,748 commits spread over many branches, the daily peak was 585 MiB. Each write from the hot session ran several FilteredRead(ScalarIndex) plans reading 25-61 MB.

    What I can't separate from outside is how much of this is the handle cache vs. the Lance data-session caches from #702 vs. allocator retention after those read bursts. The shape (a fast step as the session starts, +741 MiB in 10 minutes on 11-04, then nearly flat) doesn't look like growth linear in commit count alone. We have no heap profile or cache stats from the server. A cache-occupancy metric (#702's fourth ask) would let us tell these apart in production. In the meantime we plan to raise the limit to 4 GiB and pace that client's commits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P-highHigh priorityacceptedTriaged and validated; open for a PRperformanceCorrect result, wrong cost: work scales with the table, not with the delta or the query

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions