docs: mutations_before_rebuild is the floor of the rebuild threshold

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

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.
 
 <!-- ab-table: rebuild-threshold -->
 <!-- /ab-table -->

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