Vectors

This page covers vector search from Python. Prefer SQL and openCypher through db.command(…​) and db.query(…​) for creating an index and for searching, because a search then composes with filters, projections and graph traversal. The Python wrappers (create_vector_index, find_nearest, get_stats, build_graph_now, warm_up) are covered where no statement does the job, or where Python adds something: NumPy arrays and lists as vectors, and the index counters.

What a vector index is, its distance functions and its SQL functions belong to the main manual: Vector search, Vector embeddings and the vector functions. Bring your own embeddings from any model.

The blocks on this page run one after the other against one empty database, and a test in the repository runs them that way (tests/test_docs_vectors_page.py). Each block that prints something is followed by its output. Every block assumes that db is an open database, as on Databases and queries. NumPy is optional for the bindings, but the blocks use it; add it with uv add numpy.

Create an index

A vector index covers one property of a type. The property holds the vector, and the usual type is ARRAY_OF_FLOATS. The index needs the number of dimensions, which must match your embedding length, and a similarity (COSINE, EUCLIDEAN or DOT_PRODUCT; create_vector_index takes cosine unless you say otherwise).

import numpy as np

db.command("sql", "CREATE VERTEX TYPE Doc")
db.command("sql", "CREATE PROPERTY Doc.name STRING")
db.command("sql", "CREATE PROPERTY Doc.embedding ARRAY_OF_FLOATS")
db.command(
    "sql",
    """
    CREATE INDEX ON Doc (embedding) LSM_VECTOR
    METADATA {"dimensions": 3, "similarity": "COSINE"}
    """,
)

CREATE INDEX …​ LSM_VECTOR METADATA {…​} is the main way. The engine builds the graph of the index when the statement runs, unless the metadata holds "buildGraphNow": false.

The same index is available as a method. db.create_vector_index(…​) runs the same engine call with Python arguments and returns a VectorIndex object, which has the Python-only methods used below (find_nearest, get_stats, warm_up). It builds the graph by default too; pass build_graph_now=False to skip that. For an index made with a statement, get the object with db.schema.get_vector_index(type_name, property_name).

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:

Setting CREATE INDEX …​ LSM_VECTOR create_vector_index(…​)

quantization

NONE (full precision)

"INT8"

addHierarchy (add_hierarchy)

false (a flat graph)

True (HNSW hierarchy layers)

The index above has the engine’s values. get_metadata() shows what any index has:

index = db.schema.get_vector_index("Doc", "embedding")
meta = index.get_metadata()
print(meta["quantization"], meta["add_hierarchy"])
NONE False

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.

Insert vectors

A vector is a property value like any other. Bind it as a parameter of INSERT. A NumPy float32 array crosses into the engine as one buffer. A list of Python floats also works, and a list that is the only parameter of a statement is read as the whole parameter list, so give a vector as a list only next to other parameters or by name. The details are in A query vector.

docs = [
    ("python", [1.0, 0.0, 0.0]),
    ("python-ish", [0.9, 0.1, 0.0]),
    ("graph", [0.0, 1.0, 0.0]),
    ("vector", [0.0, 0.0, 1.0]),
]
with db.transaction():
    for name, vector in docs:
        db.command(
            "sql",
            "INSERT INTO Doc SET name = ?, embedding = ?",
            name,
            np.asarray(vector, dtype=np.float32),
        )

To load many vectors, use insert_many with one array or list per row, or insert_columns with a whole 2-D float32 matrix as one column. The vectors of a chunk cross as one buffer, not as text and not one call per number. Declare the property ARRAY_OF_FLOATS first: that is what makes the fast path apply. See Bulk loads and commit size for the commit size.

db.command("sql", "CREATE DOCUMENT TYPE Chunk")
db.command("sql", "CREATE PROPERTY Chunk.id LONG")
db.command("sql", "CREATE PROPERTY Chunk.embedding ARRAY_OF_FLOATS")

x = np.random.default_rng(0).random((100, 3), dtype=np.float32)
db.insert_many("Chunk", [{"id": i, "embedding": x[i]} for i in range(len(x))])
print(db.count_type("Chunk"))

db.insert_columns("Chunk", {"id": np.arange(len(x)), "embedding": x})
print(db.count_type("Chunk"))
100
200

GraphBatch.create_vertices rows and the properties of new_edge and new_edges take the same arrays. On the arcadedb (native) package, a non-empty one-dimensional float32 array in a row or an edge property crosses in a binary side buffer, and the stored values are bit-identical to the ones the text path gave. A list or a float64 array still crosses as number text, so make the array with np.asarray(v, dtype=np.float32) before the load. When a property holds a float32 array of one length in every row of a create_vertices call, the whole column crosses as one float32 matrix in that buffer, with no tag or Python call for each row. A laptop A/B on the native wheel (100,000 vertices for each load, ab.py --noise, ABBA order, 12 clean pairs for each figure, clean A/A control) gave this wall time of the new path against the old one (95 % interval of the median pair ratio): 0.517 [0.515, 0.520] at 128 dimensions, 0.218 [0.217, 0.219] at 96, and 0.271 [0.270, 0.272] at 64. A load without vectors was unchanged (1.009 [1.003, 1.012]).

On the arcadedb-jvm package, create_vertices sends the values of a property declared ARRAY_OF_FLOATS as one binary float32 matrix when every row holds a list, a numpy array or a Java float[] or double[] of numbers of one length. A property that is not declared takes the same matrix when every row holds a float32 numpy array or a Java float[] (what to_java_float_array returns on this package) of one length, and the stored value is a float[], as before. A list or a float64 array on an undeclared property keeps its doubles and the older path. So float32 arrays and to_java_float_array values take the binary path on both packages, declared or not.

To read many vectors, use to_columns(), to_dataframe(), to_arrow() or to_polars(). to_list() builds one Python list of floats for each vector. A column is a vector column when its values are float[], which is what a property declared ARRAY_OF_FLOATS holds; a LIST property of numbers is a list column. to_columns() returns a (count, dim) float32 matrix, with a row of NaN for a null vector. to_dataframe() returns one float32 numpy array in each cell, and None for a null. to_arrow() returns a fixed-size list of float32, and to_polars() an Array(Float32, n). Vectors of different lengths in one result make a variable-length list column (list<double> in Arrow). The rules for nulls, batch_size and memory are in Reading large results.

SQL

vectorNeighbors(index, vector, k) returns the k nearest records. The index is named Type[property]. Expand the result in a subquery to select properties and the distance. Lower is closer for every similarity.

query = np.asarray([0.9, 0.1, 0.0], dtype=np.float32)
rows = db.query(
    "sql",
    "SELECT name, distance FROM "
    "(SELECT expand(vectorNeighbors('Doc[embedding]', ?, 2))) ORDER BY distance",
    query,
).to_list()
print([row["name"] for row in rows])
['python-ish', 'python']

Bind the query vector as a parameter, as the block does, instead of writing the numbers into the statement text. A pasted vector makes every query a new statement to parse. The function takes a fourth argument, either the search beam as a number or a map of options (efSearch, filter, where, maxDistance, groupBy, groupSize); see the vectorNeighbors reference. vector.neighbors is the same function under its dotted name.

openCypher

The Cypher procedure db.index.vector.queryNodes(index, k, vector) yields node and score. Its arguments are in that order, k before the vector. A higher score is closer. On ArcadeDB 26.11.1 and later a fourth argument, an options map, restricts the search before the top k is taken: where (a map of property to value, or a condition string) and filter (a list of nodes or record ids), for example CALL db.index.vector.queryNodes('Doc[embedding]', 2, $vec, {where: {name: 'python'}}). Without the map, and on an engine before 26.11.1, there is no filter, so a WHERE after YIELD runs on the k rows only.

rows = db.query(
    "opencypher",
    "CALL db.index.vector.queryNodes('Doc[embedding]', 2, $vec) "
    "YIELD node, score RETURN node.name AS name, score ORDER BY score DESC",
    {"vec": [0.9, 0.1, 0.0]},
).to_list()
print([row["name"] for row in rows])
['python-ish', 'python']

openCypher: SEARCH and CREATE VECTOR INDEX

From ArcadeDB 26.11.1, the engine of both packages, openCypher has the two vector statements that Neo4j users know: the SEARCH subclause of MATCH searches a vector index, and CREATE VECTOR INDEX makes one. They are ordinary statements for db.query and db.command, and both packages give the same results. The full syntax is in the main manual: SEARCH and CREATE VECTOR INDEX. This section shows what you meet from Python.

SEARCH

SEARCH follows a MATCH. It binds the node variable of the MATCH to the k records nearest to a query vector, and SCORE AS names their score. It returns the rows and the scores of db.index.vector.queryNodes above, so a higher score is closer. The block searches the index Doc[embedding] that the SQL statement made, and writes its name in backticks because of the brackets.

rows = db.query(
    "opencypher",
    "MATCH (d:Doc) "
    "SEARCH d IN (VECTOR INDEX `Doc[embedding]` FOR $vec LIMIT 2) SCORE AS score "
    "RETURN d.name AS name, score ORDER BY score DESC",
    {"vec": [0.9, 0.1, 0.0]},
).to_list()
print([row["name"] for row in rows])
['python-ish', 'python']

FOR takes the query vector and LIMIT takes k. Both can be parameters, and the vector can be a list or a NumPy array (float32 or float64). The index name can be a string parameter too: VECTOR INDEX $index.

A WHERE inside the parentheses is tested on each candidate while the search runs, so the search still finds two rows when the index holds them. A WHERE after the closing parenthesis filters the k rows that the search returned, and can leave fewer.

inside = (
    "MATCH (d:Doc) "
    "SEARCH d IN (VECTOR INDEX `Doc[embedding]` FOR $vec "
    "WHERE d.name <> 'python-ish' LIMIT 2) SCORE AS score "
    "RETURN d.name AS name ORDER BY score DESC"
)
after = (
    "MATCH (d:Doc) "
    "SEARCH d IN (VECTOR INDEX `Doc[embedding]` FOR $vec LIMIT 2) "
    "WHERE d.name <> 'python-ish' RETURN d.name AS name"
)
for statement in (inside, after):
    rows = db.query("opencypher", statement, {"vec": [0.9, 0.1, 0.0]}).to_list()
    print([row["name"] for row in rows])
['python', 'graph']
['python']

Three mistakes raise ArcadeDBError: a binding variable that is not a node variable of the MATCH pattern, OPTIONAL MATCH before SEARCH, and an index that does not exist. The last one surfaces while you read the rows, as any error of a lazy result does (see A result set is read once).

CREATE VECTOR INDEX

The statement keeps the name you give it and makes an LSM_VECTOR index, the kind that CREATE INDEX …​ LSM_VECTOR makes. A label that does not exist yet becomes a vertex type, and a vector property that is not declared yet is declared ARRAY_OF_FLOATS. The index covers the records that exist when the statement runs, and then the records written later. IF NOT EXISTS makes a second run do nothing; without it, a second run raises ArcadeDBError.

The settings go in OPTIONS {indexConfig: {…​}}, with the Neo4j names:

  • vector.dimensions: the number of dimensions, a whole number above 0. You may leave it out. The index then takes the length of the first vector that it receives, and refuses a later vector of another length with ArcadeDBError.

  • vector.similarity_function: cosine (the default) or euclidean.

  • vector.quantization.type: none (the default, the exact vectors, as in the SQL statement), scalar or binary.

Any other setting of the index goes into the same map under its own name, the name that METADATA takes in the SQL statement, for example efSearch. A name that is not known, or a setting given under two names, raises ArcadeDBError, and the statement creates nothing: no index and no type.

The block creates an index, loads the docs from above with CREATE, and reads the statement that SHOW INDEXES lists for the index. That statement names every setting that differs from the default, and always the quantization. After DROP INDEX, running it makes the same index again.

db.command(
    "opencypher",
    """
    CREATE VECTOR INDEX article_embedding IF NOT EXISTS
    FOR (n:Article) ON n.embedding
    OPTIONS {indexConfig: {`vector.dimensions`: 3, `vector.similarity_function`: 'cosine'}}
    """,
)
with db.transaction():
    for title, vector in docs:
        db.command(
            "opencypher",
            "CREATE (:Article {title: $title, embedding: $vec})",
            {"title": title, "vec": vector},
        )
shown = db.query(
    "opencypher",
    "SHOW INDEXES YIELD name, createStatement WHERE name = 'article_embedding'",
).first()
print(shown.get("createStatement"))
CREATE VECTOR INDEX `article_embedding` FOR (n:`Article`) ON n.`embedding` OPTIONS {indexConfig: {`vector.dimensions`: 3, `vector.similarity_function`: 'cosine', `vector.quantization.type`: 'none'}}

SEARCH finds the index by the name you gave it:

rows = db.query(
    "opencypher",
    "MATCH (n:Article) "
    "SEARCH n IN (VECTOR INDEX article_embedding FOR $vec LIMIT 2) SCORE AS score "
    "RETURN n.title AS title ORDER BY score DESC",
    {"vec": [0.9, 0.1, 0.0]},
).to_list()
print([row["title"] for row in rows])
['python-ish', 'python']

DROP INDEX article_embedding drops it. DROP INDEX article_embedding IF EXISTS does not raise when it is already gone.

The VectorIndex object of this page (find_nearest, get_metadata, get_stats, warm_up) is a different matter. db.schema.get_vector_index("Article", "embedding") returns it for an index made by CREATE VECTOR INDEX, whatever the name you gave it, and db.schema.list_vector_indexes() lists it. Both packages do this since the fix of ArcadeData/arcadedb-python#288.

find_nearest

VectorIndex.find_nearest(query_vector, k=10, ef_search=None, allowed_rids=None, *, include_vector=True) searches without a statement. It takes a list or a NumPy array and returns a list of (record, distance) tuples, nearest first. Use it when you already hold the index object, or when you have a list of record ids to search within.

With ef_search=None the search width comes from the index’s efSearch metadata when it is set, otherwise from the engine: max(k, 100) candidates on an index of under 10,000 vectors and max(2k, 100) from 10,000 vectors on. Before ArcadeDB 26.11.1 the larger indexes searched max(2k, 20), which gave recall@10 0.929 on SIFT 100k against 0.998 now (ArcadeData/arcadedb#10704), so a search on a large index is more accurate and slower than on earlier releases. Pass a smaller ef_search to trade recall for speed, or a larger one for more recall.

The second element of each tuple is a distance, and lower is closer, for every similarity function (COSINE, EUCLIDEAN and DOT_PRODUCT) and on both packages. find_nearest sorts the hits by it, ascending. It is the distance column of vectorNeighbors, not the score of the Cypher procedure above, where higher is closer.

VectorIndex.find_nearest_by_key(key, k=10, ef_search=None, allowed_rids=None) searches with the stored vector of an existing record as the query, so you do not fetch the vector first. key is the value of the index’s id property for that record. get_metadata()["id_property"] names that property, and create_vector_index(…​, id_property=…​) sets it. The other arguments and the result are those of find_nearest. The call raises ArcadeDBError when no record has that key, or when the record’s vector property is null.

On the native package the query vector crosses as one float32 buffer whatever its form (a list, a float64 array, or a float32 array), so you do not need to convert it first. A vector index stores float32, so the numbers are rounded the same way as before. The table gives the median find_nearest latency with this change over the median without it (95% interval, below 1 is faster), measured on the native wheel 26.11.1.dev0 on one Linux x86_64 laptop with 11 to 12 clean pairs per figure. The wheel built before this change was the baseline.

Query passed as 1536 dimensions 256 dimensions

find_nearest, a float32 array

0.951 [0.945, 0.954]

0.952 [0.942, 0.96]

find_nearest, a float64 array

0.616 [0.614, 0.621]

0.777 [0.774, 0.781]

find_nearest, a list of Python floats

0.631 [0.627, 0.635]

0.792 [0.787, 0.798]

vectorNeighbors statement with a float32 array (not changed)

1.003 [0.995, 1.014]

1.004 [0.991, 1.006]

for record, distance in index.find_nearest(query, k=2):
    print(record.get("name"))
python-ish
python

Hits without the vector

Every hit of find_nearest carries its indexed vector, so a search at 1536 dimensions ships and decodes 1536 numbers per hit whether you read them or not. If you need only the ids, the distances or other properties of the hits, pass include_vector=False. On the native build each hit is then built without the vector. It loads the vector, with the rest of the record, in one lookup by record id the first time you read it (get of the vector, has_property, to_dict, get_property_names, modify or save). The values are the ones db.lookup_by_rid returns, and a hit deleted since the search raises ArcadeDBError on that first read. The arcadedb-jvm package accepts the argument and returns whole records either way, so the call costs the same there.

This is an opt-in for callers that do not read the vector. The default stays include_vector=True: every hit carries its vector, and the default call is the one described above, unchanged. A loop that reads the vector of every hit after passing include_vector=False pays one lookup per hit and does more work than the default call, so do not pass it for that.

The table gives the median find_nearest latency over the median of the default call before this change (95% interval, below 1 is faster), with k = 10 on 100,000 vectors per dimension count. It was measured on the native wheel 26.11.1.dev0 (the engine inside it is 26.10.2) on one Linux x86_64 laptop with 12 clean pairs per figure. The default call has not changed: its intervals lie between 0.993 and 1.011. With the keyword set, a search whose hits are not read, or whose ids are read, is faster at both sizes. If every vector is read afterwards, the call takes 1.0 [0.999, 1.004] times as long as the default call at 1536 dimensions and 1.348 [1.34, 1.352] times as long at 256 dimensions.

Call 1536 dimensions 256 dimensions

include_vector=False, hits not read

0.637 [0.633, 0.641]

0.8 [0.793, 0.818]

include_vector=False, hit ids read

0.637 [0.633, 0.638]

0.797 [0.793, 0.803]

include_vector=False, then the vector of every hit read

1.0 [0.999, 1.004]

1.348 [1.34, 1.352]

the default call, hits not read (not changed)

1.0 [0.996, 1.002]

1.005 [0.996, 1.011]

the default call, hit ids read (not changed)

1.001 [0.997, 1.005]

1.002 [0.994, 1.005]

the default call, the vector of every hit read (not changed)

0.997 [0.995, 1.005]

0.997 [0.993, 1.007]

for record, distance in index.find_nearest(query, k=2, include_vector=False):
    print(record.get("name"))
python-ish
python

allowed_rids restricts find_nearest to the records whose ids you list, as strings. The search considers only those records, so it still returns k of them.

rows = db.query(
    "sql",
    "SELECT @rid AS rid FROM Doc WHERE name IN :names",
    {"names": ["graph", "vector"]},
).to_list()
allowed = [str(row["rid"]) for row in rows]
for record, distance in index.find_nearest(query, k=2, allowed_rids=allowed):
    print(record.get("name"))
graph
vector

In SQL, the filter option of vectorNeighbors does the same with a list of record ids written in the statement. The where option tests a condition on each candidate as the search reaches it (a map of property to value, or a condition string).

On ArcadeDB 26.11.1 and later, a selective where on an indexed property uses the property index, in vectorNeighbors and in db.index.vector.queryNodes alike: the search starts walking the graph, and when the condition keeps few records it lists them through the index and scores them directly. A broad condition keeps walking. Index the property you filter on, for example CREATE INDEX ON Doc (name) NOTUNIQUE. A condition on a property without an index still loads candidates to test them, as before. The plan and its measurements are in ArcadeData/arcadedb#10921.

Filtering the rows afterwards is the simplest way. The search runs first and the filter second, so ask for more neighbours than you need. A filter that drops rows can leave fewer than you asked for.

rows = db.query(
    "sql",
    "SELECT name, distance FROM "
    "(SELECT expand(vectorNeighbors('Doc[embedding]', ?, 4))) "
    "WHERE name <> ? ORDER BY distance LIMIT 2",
    query,
    "python-ish",
).to_list()
print([row["name"] for row in rows])
['python', 'graph']

Quantization

quantization takes INT8, BINARY, PRODUCT (product quantization), or none (full precision). In a statement, it is a key of the METADATA. In the method, it is the quantization argument, and quantization=None means full precision. The defaults differ, as the table above shows: the statement gives NONE, and create_vector_index gives INT8.

db.command("sql", "CREATE VERTEX TYPE Note")
db.command("sql", "CREATE PROPERTY Note.title STRING")
db.command("sql", "CREATE PROPERTY Note.embedding ARRAY_OF_FLOATS")
with db.transaction():
    for title, vector in docs:
        db.command(
            "sql",
            "INSERT INTO Note SET title = ?, embedding = ?",
            title,
            np.asarray(vector, dtype=np.float32),
        )

notes = db.create_vector_index(
    "Note", "embedding", dimensions=3, mutations_before_rebuild=5000
)
meta = notes.get_metadata()
print(meta["quantization"], meta["add_hierarchy"])
INT8 True

These rules hold for the quantization arguments of the method:

  • The pq_* and fused_pq arguments need quantization="PRODUCT". rerank_oversample needs "PRODUCT" or, on ArcadeDB 26.11.1 and later, "BINARY": a BINARY search scores the one-bit codes and re-ranks k * rerank_oversample candidates on the stored vectors (default 10), or the whole efSearch beam when that is larger (ArcadeData/arcadedb#10968). The call raises ValueError otherwise. The same keys are METADATA keys in a statement (pqSubspaces, pqClusters, pqCenterGlobally, pqTrainingLimit, rerankOversample, fusedPQ). With PRODUCT, from ArcadeDB 26.11.1 a graph rebuild keeps the trained codebook and encodes only the vectors added since (ArcadeData/arcadedb#10847). The engine trains a new codebook and re-encodes every vector when the index has grown past arcadedb.vectorIndex.pqRetrainGrowthFactor times its size at training (default 2.0), or when the new vectors encode worse than the training ones (arcadedb.vectorIndex.pqRetrainErrorRatio, default 1.25). Setting the growth factor to 0 restores a retrain on every rebuild, which is what engines before 26.11.1 do. Measure recall and rebuild time on your own data before you choose PRODUCT.

  • encoding="INT8" is for a BINARY property that already holds INT8 bytes. Set quantization to "NONE" with it. The call raises ValueError when both are INT8, because the vector would be quantized twice.

  • A bucket that holds fewer vectors than pq_clusters is too small to train a codebook. The index still builds: the engine skips PQ for that bucket and searches it exactly, so find_nearest_approximate returns the exact neighbours with exact scores from it. A bucket with pq_clusters vectors or more is trained and answers approximately.

Rebuild the graph

Inserts, updates and deletes collect as pending changes. When enough of them have collected, the engine rebuilds the graph in the background, and searches keep running. How many is enough comes from the database setting arcadedb.vectorIndex.rebuildGraphRatio and from mutations_before_rebuild; see Database settings for how to change the ratio.

The background rebuild starts on the first search after the threshold is reached, so an index that only takes writes rebuilds when it is next searched.

mutations_before_rebuild is a floor, not an override. The threshold is the larger of the floor and the ratio term (the graph size times the ratio, capped by arcadedb.vectorIndex.maxPendingMutations). A value below the ratio term changes nothing. Raise it above that term to rebuild less often. To rebuild sooner, lower the ratio.

To see the value in force, and the other live counters, call get_stats(). It returns a dict of counter names to numbers (cache hits and misses, where vectors were read from, graph state). The keys follow the engine and can change between releases. get_metadata() is the stable configuration of the index instead.

stats = notes.get_stats()
print(stats["totalVectors"], stats["effectiveMutationsThreshold"])

before = stats["searchOperations"]
notes.find_nearest(query, k=1)
print(notes.get_stats()["searchOperations"] > before)
4 5000
True

build_graph_now() rebuilds the graph at once and returns when the graph is built. Call it after a bulk load, so that no search waits for a lazy build. From ArcadeDB 26.11.1, the engine these bindings ship, searches keep answering while it runs, from the graph in memory plus the vectors written since, and switch to the new graph when it is ready, as during the automatic background rebuild. Engines before 26.11.1 made every search on that index wait until the build returned. An index with no graph in memory yet, for example one not searched since the database was opened, still makes searches wait, because there is nothing else to answer from; warm_up() below loads it first. Inserts carry on. Ctrl-C takes effect only when it returns, and a process killed during the build leaves a consistent database whose next build covers every vector.

The reads of a VectorIndex you hold (get_size(), get_metadata(), get_quantization(), get_stats()) ask the engine each time. After DROP INDEX they raise an error that names the index, and after the index is created again they report its new configuration.

After you open a database, an index loads its saved graph on the first search, and that search pays the load. A service that restarts can call warm_up() on the index right after open_database, to pay it before the first query. It loads the saved graph and does not rebuild it, and it does nothing when the graph is in memory already.

notes.build_graph_now()
notes.warm_up()
print(notes.get_size())
4

Agents that write as they go

An agent that writes one record per turn and searches right after needs no setting: the rebuild runs in the background and the searches keep running while it does.

A search finds every vector whose transaction committed before the search started. Insert in one call and search in the next, from the same task or from another one, and the new vector is in the result, also while the graph rebuilds in the background. From asyncio, use AsyncDatabase (asyncio: AsyncDatabase) or run each call with asyncio.to_thread as Concurrency describes: the insert and the search of one task can run on different threads and the search still finds the vector. This holds for committed writes only. It says nothing about a search made while the writing transaction is still open.

If the tail of the search latency matters more than the agent’s total time, you can move the rebuild to a moment of your choosing: raise mutations_before_rebuild far above the number of writes, set the database setting arcadedb.vectorIndex.maxDeltaScanRatio to 0, and call build_graph_now() right before a step in which the agent does not search, such as its call to the language model.

The table compares the two on arcadedb-jvm and arcadedb 26.11.1.dev0: 768-dimensional COSINE vectors, 10,000 records at the start, one insert and four k = 10 searches per turn at efSearch 100, build_graph_now() every 1,000 turns, two efficiency cores of a laptop, the first 3,000 turns. Each ratio is the median over paired runs of the same package; the two packages ran separately and are not compared with each other.

Table 1. Default background rebuild against build_graph_now() before the model call
Package Search p99, default Search p99, build_graph_now() Loop seconds, default to build_graph_now() Insert p99, ratio

arcadedb-jvm

5.10 ms (5.50 ms during the rebuild)

1.82 ms (ratio 0.361, 95% CI 0.339 to 0.394)

22 to 37 (1.633 times)

0.408 times

arcadedb

2.41 ms (2.53 ms during the rebuild)

1.54 ms (ratio 0.643, 95% CI 0.639 to 0.646)

24 to 43 (1.782 times)

2.998 times

The agent waits for each build_graph_now() call, so the loop takes longer, and on arcadedb the insert p99 rose while on arcadedb-jvm it fell. Reads stayed complete and recall@10 did not move in either arm. Giving the background rebuild more threads (arcadedb.vectorIndex.graphBuildParallelism set to the number of cores) raised the search p99 instead, with a ratio of 1.12 on arcadedb-jvm and 2.205 on arcadedb.

Distance kernels in the native package

The two packages compute vector distances differently. arcadedb-jvm runs jvector’s Panama kernels on the Java Vector API. arcadedb is built without the Vector API, so on Linux x86_64 and aarch64 it uses jvector’s Highway kernels, a native library the wheel ships next to the engine, and on macOS and Windows jvector’s scalar Java kernels.

To choose, set ARCADEDB_VECTOR_PROVIDER before the first database is opened in the process: native for Highway (the default where the wheel ships it) or default for the scalar kernels. In our laptop measurement (medians, 100,000 vectors, 26.11.1.dev0) Highway built indexes 2.2 to 2.5 times faster and answered queries 14 to 30 percent faster than the scalar kernels at 768 and 1536 dimensions; at 128 dimensions the build took the same time and queries were 6 percent slower. Both return the same results.

For vector search the JVM package is faster still: see Which package?.