From a9b79f90827d000dd289eb3450aab0dc10338fd1 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Thu, 29 Oct 2026 00:04:51 +0900 Subject: [PATCH] docs: mutations_before_rebuild is the floor of the rebuild threshold The engine computes max(mutationsBeforeRebuild, min(graph size x rebuildGraphRatio, maxPendingMutations)) in 26.10.1, 26.10.2 and main (computeRebuildThreshold, read from the database configuration), so the "override" wording and the 26.10.1 workaround "a lower mutations_before_rebuild" were wrong past 500 vectors. The guide now gives the formula and the ALTER DATABASE route for rebuildGraphRatio (main c3af6d9028: 1,000 to 250 at 5,000 vectors). Same fix as ArcadeData/arcadedb-python#111 and #113. Closes #549 Co-Authored-By: Claude Opus 5.5 --- bindings/python/docs/api/database.md | 2 +- bindings/python/docs/guide/vectors.md | 20 ++++++++++++++++--- bindings/python/src/arcadedb_embedded/core.py | 12 ++++++----- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/bindings/python/docs/api/database.md b/bindings/python/docs/api/database.md index 9f63de1dd64..58df498b4c1 100644 --- a/bindings/python/docs/api/database.md +++ b/bindings/python/docs/api/database.md @@ -1366,7 +1366,7 @@ specifically need that surface. value raises `ValueError`; the engine no longer accepts the setting because bounding the vector-location index drops vectors from searches rather than spilling to disk. - `graph_build_cache_size` (int | None): Override the number of vectors cached while the graph is built (default: `None`, the engine's automatic sizing; leave it unset, see [Build-time cache](../guide/vectors.md#build-time-cache-use-the-default)). -- `mutations_before_rebuild` (int | None): Override rebuild threshold (default: `None`, uses engine default). +- `mutations_before_rebuild` (int | None): Floor of the graph rebuild threshold (default: `None`, the engine default 100). The threshold is `max(floor, min(graph size × rebuildGraphRatio, maxPendingMutations))`, so above 500 vectors at the default ratio 0.2 a lower floor changes nothing; to rebuild sooner, lower `arcadedb.vectorIndex.rebuildGraphRatio` with `ALTER DATABASE` (see [Searches while the graph rebuilds](../guide/vectors.md#searches-while-the-graph-rebuilds)). - `store_vectors_in_graph` (bool): Persist vectors inline in graph file (faster reopen/search, larger graph). - `add_hierarchy` (bool | None): Force enabling/disabling HNSW hierarchy (default: `True`). The default is a deliberate choice of these bindings. The engine itself defaults to diff --git a/bindings/python/docs/guide/vectors.md b/bindings/python/docs/guide/vectors.md index 30e49987b7f..7f9faea669e 100644 --- a/bindings/python/docs/guide/vectors.md +++ b/bindings/python/docs/guide/vectors.md @@ -186,9 +186,23 @@ of the vectors not yet in the graph (ArcadeDB [#7260](https://github.com/ArcadeData/arcadedb/issues/7260)). Upstream fixed it in [#9289](https://github.com/ArcadeData/arcadedb/pull/9289), merged on 2026-10-06 and released in ArcadeDB 26.10.2; the 26.10.1 wheel still has it. On 26.10.1, a -heap of about twice the graph, a lower `mutations_before_rebuild`, or rebuilding in a quiet window -avoids it. Read-mostly use, and loading first and -serving after, never meet it. +heap of about twice the graph, or rebuilding in a quiet window, avoids it. Read-mostly use, and +loading first and serving after, never meet it. + +The engine rebuilds the graph after +`max(mutationsBeforeRebuild, min(graph size × rebuildGraphRatio, maxPendingMutations))` +mutations, with defaults 100, 0.2 and 50,000 (the same formula in 26.10.1, 26.10.2 and later). +`mutations_before_rebuild` is the floor of that threshold, not an override: above 500 vectors +the ratio term is larger, so raising the floor delays rebuilds of a small index, and lowering it +changes nothing on a large one. To rebuild a large index sooner, lower the ratio. It is a +database setting, read when the threshold is computed: + +```python +db.command("sql", "ALTER DATABASE `arcadedb.vectorIndex.rebuildGraphRatio` 0.05") +``` + +At 5,000 vectors this takes the threshold from 1,000 to 250 mutations (checked on ArcadeDB main +`c3af6d9028`). `index.get_stats()["effectiveMutationsThreshold"]` reports the value in force. diff --git a/bindings/python/src/arcadedb_embedded/core.py b/bindings/python/src/arcadedb_embedded/core.py index 7566eab0532..2cf88411ab9 100644 --- a/bindings/python/src/arcadedb_embedded/core.py +++ b/bindings/python/src/arcadedb_embedded/core.py @@ -1477,11 +1477,13 @@ def create_vector_index( below the corpus makes the build re-read vectors from the documents. Set an absolute count only to bound a build on a deliberately small heap. - mutations_before_rebuild: Per-index override for mutations threshold - before triggering a graph rebuild (maps to Java metadata key - "mutationsBeforeRebuild"; uses GlobalConfiguration default if None). - Typical ranges: 100–300 for freshness-heavy workloads; 300–800 for - write-heavy workloads and larger graphs. + mutations_before_rebuild: Floor of the graph rebuild threshold (Java + metadata key "mutationsBeforeRebuild"; the engine default 100 if + None). The engine rebuilds after max(floor, min(graph size x + rebuildGraphRatio, maxPendingMutations)) mutations, so above + floor / 0.2 vectors the ratio decides and a lower floor changes + nothing. To rebuild sooner, lower the database setting + arcadedb.vectorIndex.rebuildGraphRatio with ALTER DATABASE. pq_subspaces: Number of PQ subspaces (M). Requires quantization="PRODUCT". pq_clusters: Clusters per subspace (K). Requires quantization="PRODUCT". In current ArcadeDB engine builds, this should not exceed the