From 9fc5d1bad3617c714412dca1eda3ea4030350156 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Wed, 28 Oct 2026 23:49:35 +0900 Subject: [PATCH] Docs: change a database-scope engine setting with ALTER DATABASE (#112) Every SCOPE.DATABASE setting (all of arcadedb.vectorIndex.*) is set on one database with SQL, which db.command already runs, so the bindings need no wrapper (DSL first). Checked on engine main c3af6d9028: effectiveMutationsThreshold at 5000 vectors goes 1000 -> 250 after ALTER DATABASE `arcadedb.vectorIndex.rebuildGraphRatio` 0.05, and a SCOPE.SERVER setting is refused with a message naming SET SERVER SETTING. databases-and-queries.adoc gets a short section, the create_vector_index docstring the statement, and a test pins it on both wheels (1000 vectors: threshold 200, then 500 with the ratio at 0.5). Co-Authored-By: Claude Opus 5.5 --- .../ROOT/pages/how-to/databases-and-queries.adoc | 11 +++++++++++ src/arcadedb/core.py | 3 ++- tests/test_vector_index_introspection.py | 13 +++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/how-to/databases-and-queries.adoc b/docs/modules/ROOT/pages/how-to/databases-and-queries.adoc index c6a9bed..9497517 100644 --- a/docs/modules/ROOT/pages/how-to/databases-and-queries.adoc +++ b/docs/modules/ROOT/pages/how-to/databases-and-queries.adoc @@ -263,6 +263,17 @@ The same two calls run openCypher: pass `"opencypher"` as the language. The scri NOTE: ArcadeDB SQL has no JOINs, so SQLAlchemy and other ORMs, and tools that generate `JOIN` queries, do not work with these two calls. Write the statements yourself, following links as in xref:arcadedb::reference/sql/sql-introduction.adoc#no-joins[No JOINs], or use openCypher for relationships. +== Database settings + +An engine setting of scope `DATABASE`, which includes every `arcadedb.vectorIndex.*` setting, is changed on one open database with SQL, which `db.command` runs like any other statement: + +[source,python] +---- +db.command("sql", "ALTER DATABASE `arcadedb.vectorIndex.rebuildGraphRatio` 0.05") +---- + +The key is backquoted because it contains dots. The change applies to that database only. A setting of scope `SERVER` is refused there, with a message that names `SET SERVER SETTING`. For the vector settings, the index statistics show the value in force: `index.get_stats()["effectiveMutationsThreshold"]` is the number of changes after which the graph is rebuilt, computed from `mutations_before_rebuild`, `rebuildGraphRatio` and `maxPendingMutations` (see the `create_vector_index` docstring). + == Next steps * xref:quickstart.adoc[Quickstart] diff --git a/src/arcadedb/core.py b/src/arcadedb/core.py index 0b9b9d0..00f060a 100644 --- a/src/arcadedb/core.py +++ b/src/arcadedb/core.py @@ -1553,7 +1553,8 @@ def create_vector_index( value below the ratio term has no effect: at 100000 vectors the threshold is 20000 whether this is 100 or 800. Raise it above that term to rebuild less often. To rebuild sooner, lower - rebuildGraphRatio (a database-scope setting); with the ratio at 0 + rebuildGraphRatio, a database-scope setting (db.command("sql", + "ALTER DATABASE `arcadedb.vectorIndex.rebuildGraphRatio` 0.05")); with the ratio at 0 the threshold is exactly this value. pq_subspaces: Number of PQ subspaces (M). Requires quantization="PRODUCT". pq_clusters: Clusters per subspace (K). Requires quantization="PRODUCT". diff --git a/tests/test_vector_index_introspection.py b/tests/test_vector_index_introspection.py index 0efb182..999720b 100644 --- a/tests/test_vector_index_introspection.py +++ b/tests/test_vector_index_introspection.py @@ -257,3 +257,16 @@ def test_the_threshold_is_the_larger_of_the_floor_and_the_ratio_term( stats = index.get_stats() assert stats["totalVectors"] == len(self.ROWS) assert stats["effectiveMutationsThreshold"] == expected + + def test_alter_database_sets_the_ratio_the_threshold_reads(self, temp_db): + # the route the docs give for a database-scope setting (#112): SQL, no Python wrapper + _make_type(temp_db) + _insert(temp_db, self.ROWS) + index = temp_db.create_vector_index("Doc", "embedding", dimensions=3) + assert index.get_stats()["effectiveMutationsThreshold"] == 200 + + temp_db.command( + "sql", "ALTER DATABASE `arcadedb.vectorIndex.rebuildGraphRatio` 0.5" + ) + + assert index.get_stats()["effectiveMutationsThreshold"] == 500