Skip to content

create_vector_index: mutations_before_rebuild is a floor of the rebuild threshold, not an override #110

Closed

Description

@tae898

The create_vector_index docstring calls mutations_before_rebuild a "per-index override for mutations threshold" and suggests "100-300 for freshness-heavy workloads; 300-800 for write-heavy workloads and larger graphs". The engine treats it as a floor, not an override: LSMVectorIndex.computeRebuildThreshold returns max(mutationsBeforeRebuild, min(graphSize * rebuildGraphRatio, maxPendingMutations)) whenever arcadedb.vectorIndex.rebuildGraphRatio is above 0 (defaults: floor 100, ratio 0.2, arcadedb.vectorIndex.maxPendingMutations 50,000), and the engine's own description of rebuildGraphRatio says it applies "on top of the absolute mutationsBeforeRebuild floor". The formula is the same on 26.10.1, 26.10.2 and current main.

So every value up to 20% of the graph has no effect: at 100,000 vectors the index rebuilds after 20,000 changes whether mutations_before_rebuild is 100 or 800, and the suggested ranges change nothing past a few thousand vectors. Raising it above the ratio-based term does take effect, and with the ratio at 0 the threshold is exactly this value. Found while designing an agent-memory workload study, where the "lower" setting turned out to be a no-op.

Fix: describe it as the floor it is, with the formula, the defaults, and the setting that actually lowers the threshold (rebuildGraphRatio, a database-scope setting), plus a regression test that pins the floor through get_stats()["effectiveMutationsThreshold"].

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions