Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/modules/ROOT/pages/how-to/vectors.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
|===
Expand All @@ -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)
|===

Expand All @@ -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

Expand Down
9 changes: 5 additions & 4 deletions src/arcadedb/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 21 additions & 1 deletion tests/test_docs_vectors_page.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 (
Expand Down
28 changes: 23 additions & 5 deletions tests/test_vector_sql.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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_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_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 False
# The vector guide says the same of quantization: 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")
Expand All @@ -1342,7 +1360,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 engine_default

def test_sql_graph_settings_default_to_the_engines(self, test_db):
self._make_docs(test_db)
Expand Down
Loading