From a3e7a9c63680c5ff55762aa81bb8f2d359e371f1 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Sat, 21 Nov 2026 23:56:42 +0900 Subject: [PATCH 1/2] Vector index: the engine now builds a hierarchy by default, so the docs and one test say so ArcadeData/arcadedb#12616 (engine 26.12.1) makes new LSM vector indexes hierarchical by default. A SQL CREATE INDEX without addHierarchy now agrees with create_vector_index(), and only quantization still differs. The how-to page, the docstring of create_vector_index and test_add_hierarchy_default_agrees_between_sql_and_python name the old default (a flat graph) and failed on the snapshot engine since 2026-11-20, which turns the platform tests of every pull request red. The page says the old default for 26.11.1 and earlier. Closes #418 --- docs/modules/ROOT/pages/how-to/vectors.adoc | 8 ++++---- src/arcadedb/core.py | 9 +++++---- tests/test_vector_sql.py | 10 +++++----- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/how-to/vectors.adoc b/docs/modules/ROOT/pages/how-to/vectors.adoc index 828a51e..7645564 100644 --- a/docs/modules/ROOT/pages/how-to/vectors.adoc +++ b/docs/modules/ROOT/pages/how-to/vectors.adoc @@ -35,7 +35,7 @@ The same index is available as a method. `db.create_vector_index(...)` runs the === The two paths have different defaults -The statement follows the engine, and the method follows the choices of these bindings. The two build different indexes from the same dimensions and similarity: +The statement follows the engine, and the method follows the choices of these bindings. The two build different indexes from the same dimensions and similarity (on 26.11.1 and earlier the graph shape differs as well): [cols="2,2,2"] |=== @@ -46,7 +46,7 @@ The statement follows the engine, and the method follows the choices of these bi | `"INT8"` | `addHierarchy` (`add_hierarchy`) -| `false` (a flat graph) +| `true` (HNSW hierarchy layers) from engine 26.12.1; `false` (a flat graph) on 26.11.1 and earlier | `True` (HNSW hierarchy layers) |=== @@ -61,10 +61,10 @@ print(meta["quantization"], meta["add_hierarchy"]) [source,text] ---- -NONE False +NONE True ---- -Name the setting in the statement or in the call when you compare results or need the same index from both paths. `"quantization": "INT8"` and `"addHierarchy": true` in the `METADATA` give the method's index; `quantization=None` and `add_hierarchy=False` in the call give the statement's. Do not take `INT8` as the best choice from its being the method's default: check recall and speed on your own data. +Name the setting in the statement or in the call when you compare results or need the same index from both paths. `"quantization": "INT8"` and `"addHierarchy": true` in the `METADATA` give the method's index; `quantization=None` in the call gives the statement's (and `add_hierarchy=False` on 26.11.1 and earlier, where the statement builds a flat graph). Do not take `INT8` as the best choice from its being the method's default: check recall and speed on your own data. == Insert vectors diff --git a/src/arcadedb/core.py b/src/arcadedb/core.py index 29ef657..9483f35 100644 --- a/src/arcadedb/core.py +++ b/src/arcadedb/core.py @@ -1714,10 +1714,11 @@ def create_vector_index( lookups. add_hierarchy: Whether to build hierarchical layers in the HNSW graph (Default is True). If None, uses the engine default. Set explicitly to - True/False to force the behavior. The default of True is a deliberate - choice of these bindings: the engine itself defaults to False, so a - SQL ``CREATE INDEX ... LSM_VECTOR`` without ``"addHierarchy"`` builds a - flat graph. Record the value you use when you compare results. + True/False to force the behavior. From engine 26.12.1 the engine builds + a hierarchy by default too (ArcadeData/arcadedb#12616), so a SQL + ``CREATE INDEX ... LSM_VECTOR`` without ``"addHierarchy"`` agrees with + this default; on 26.11.1 and earlier it builds a flat graph. Record the + value you use when you compare results. Returns: VectorIndex object diff --git a/tests/test_vector_sql.py b/tests/test_vector_sql.py index f324eac..6cff78c 100644 --- a/tests/test_vector_sql.py +++ b/tests/test_vector_sql.py @@ -1321,12 +1321,12 @@ def test_graph_build_settings_reach_the_index(self, test_db): assert float(meta.alphaDiversityRelaxation) == pytest.approx(1.4) assert bool(meta.addHierarchy) is True - def test_add_hierarchy_defaults_differ_between_sql_and_python(self, test_db): - """SQL follows the engine (flat graph); create_vector_index() builds a hierarchy.""" + def test_add_hierarchy_default_agrees_between_sql_and_python(self, test_db): + """From engine 26.12.1 (ArcadeData/arcadedb#12616) SQL and create_vector_index() both build a hierarchy; quantization still differs.""" self._make_docs(test_db) meta = test_db.schema.get_vector_index("OptDoc", "embedding").get_metadata() - assert meta["add_hierarchy"] is False - # The vector guide says the same of quantization: SQL is the engine's NONE. + assert meta["add_hierarchy"] is True + # Quantization still differs, as the vector guide says: SQL is the engine's NONE. assert meta["quantization"] == "NONE" test_db.command("sql", "CREATE VERTEX TYPE PyHier") @@ -1342,7 +1342,7 @@ def test_add_hierarchy_defaults_differ_between_sql_and_python(self, test_db): engine_default_index = test_db.create_vector_index( "PyEngineDefault", "embedding", dimensions=2, add_hierarchy=None ) - assert engine_default_index.get_metadata()["add_hierarchy"] is False + assert engine_default_index.get_metadata()["add_hierarchy"] is True def test_sql_graph_settings_default_to_the_engines(self, test_db): self._make_docs(test_db) From e80bf4744cc616711b75e7405382c52ac5994cc8 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Sun, 22 Nov 2026 00:18:24 +0900 Subject: [PATCH 2/2] Vector tests: each expects the hierarchy default of the engine it runs on The same two tests run on the snapshot engine (a hierarchy by default since ArcadeData/arcadedb#12616) and, in the installed-wheel parity job, on a wheel with engine 26.11.1 (a flat graph from SQL). They now read the engine version through SELECT version(), as test_docs_facets_page.py does, and expect the default of that engine; the page keeps showing the 26.12.1 value. --- tests/test_docs_vectors_page.py | 22 +++++++++++++++++++++- tests/test_vector_sql.py | 28 +++++++++++++++++++++++----- 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/tests/test_docs_vectors_page.py b/tests/test_docs_vectors_page.py index f7b698d..adf72ec 100644 --- a/tests/test_docs_vectors_page.py +++ b/tests/test_docs_vectors_page.py @@ -37,6 +37,23 @@ def _blocks(): return found +HIERARCHY_SINCE = ( + 26, + 12, + 1, +) # the engine builds a hierarchy by default from here (ArcadeData/arcadedb#12616) + + +def _engine_version(db): + """The engine's x.y.z through SQL `SELECT version()`; a SNAPSHOT or a build suffix is dropped.""" + raw = str(db.query("sql", "SELECT version() AS v").first().get("v")) + parts = [ + int(p) if p.isdigit() else 0 + for p in raw.split()[0].split("-")[0].split(".")[:3] + ] + return tuple(parts + [0] * (3 - len(parts))) + + def test_the_page_has_its_blocks(): blocks = _blocks() assert len(blocks) >= 10 @@ -45,14 +62,17 @@ def test_the_page_has_its_blocks(): def test_every_block_runs_in_order_and_prints_what_the_page_says(temp_db): namespace = {"db": temp_db, "__name__": "vectors_page"} + newer = _engine_version(temp_db) >= HIERARCHY_SINCE for number, (code, expected) in enumerate(_blocks(), start=1): captured = io.StringIO() compiled = compile(code, f"vectors.adoc python block {number}", "exec") with contextlib.redirect_stdout(captured): exec(compiled, namespace) # nosec B102 - the page of this repository if expected is not None: + # the page shows the engine of this release; an older engine (the parity job's 26.11.1) builds a flat graph from SQL + want = expected if newer else expected.replace("NONE True", "NONE False") assert ( - captured.getvalue().strip() == expected.strip() + captured.getvalue().strip() == want.strip() ), f"block {number} printed other text than the page shows:\n{code}" else: assert ( diff --git a/tests/test_vector_sql.py b/tests/test_vector_sql.py index 6cff78c..7722ed3 100644 --- a/tests/test_vector_sql.py +++ b/tests/test_vector_sql.py @@ -1135,6 +1135,19 @@ def _engine_version(db): WHERE_SINCE = (26, 11, 1) +HIERARCHY_SINCE = (26, 12, 1) # the engine builds a hierarchy by default from here + + +def _engine_version(db): + """The engine's x.y.z through SQL `SELECT version()`; a SNAPSHOT or a build suffix is dropped.""" + raw = str(db.query("sql", "SELECT version() AS v").first().get("v")) + parts = [ + int(p) if p.isdigit() else 0 + for p in raw.split()[0].split("-")[0].split(".")[:3] + ] + return tuple(parts + [0] * (3 - len(parts))) + + class TestVectorSearchOptionsSql: """The vector.neighbors option map and index metadata the vector guide documents. @@ -1321,12 +1334,17 @@ def test_graph_build_settings_reach_the_index(self, test_db): assert float(meta.alphaDiversityRelaxation) == pytest.approx(1.4) assert bool(meta.addHierarchy) is True - def test_add_hierarchy_default_agrees_between_sql_and_python(self, test_db): - """From engine 26.12.1 (ArcadeData/arcadedb#12616) SQL and create_vector_index() both build a hierarchy; quantization still differs.""" + def test_add_hierarchy_default_follows_the_engine_and_python_builds_a_hierarchy( + self, test_db + ): + """SQL follows the engine: a flat graph before engine 26.12.1, a hierarchy from it + (ArcadeData/arcadedb#12616). create_vector_index() builds a hierarchy on every engine. + """ + engine_default = _engine_version(test_db) >= HIERARCHY_SINCE self._make_docs(test_db) meta = test_db.schema.get_vector_index("OptDoc", "embedding").get_metadata() - assert meta["add_hierarchy"] is True - # Quantization still differs, as the vector guide says: SQL is the engine's NONE. + assert meta["add_hierarchy"] is engine_default + # Quantization differs on every engine, as the vector guide says: SQL is the engine's NONE. assert meta["quantization"] == "NONE" test_db.command("sql", "CREATE VERTEX TYPE PyHier") @@ -1342,7 +1360,7 @@ def test_add_hierarchy_default_agrees_between_sql_and_python(self, test_db): engine_default_index = test_db.create_vector_index( "PyEngineDefault", "embedding", dimensions=2, add_hierarchy=None ) - assert engine_default_index.get_metadata()["add_hierarchy"] is True + assert engine_default_index.get_metadata()["add_hierarchy"] is engine_default def test_sql_graph_settings_default_to_the_engines(self, test_db): self._make_docs(test_db)