Docs: change a database-scope engine setting with ALTER DATABASE

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]

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".

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