Vector search support (Option A: Cassandra 5 SAI, Option B: ES/OS vector fields)

[tae898]

Motivation

• Many JanusGraph users run Cassandra and/or Elasticsearch/OpenSearch. Both now support vector types with ANN.
• Today embeddings can be stored but not queried in JanusGraph.

Option A – Cassandra SAI (from v5.0)

• New mixed index backend: cassandra_sai.
• Schema: Mapping.vector(dim).metric(...).
• Gremlin: has('emb', knn(vec).k(20).metric("cosine")).
• Planner → CQL ORDER BY emb ANN OF [...] LIMIT k.

Option B – Extend existing backends

• Reuse Elasticsearch/OpenSearch mixed index.
• Add vector mapping and knn(...) predicate.
• Uses ES/OS ANN APIs (dense_vector / knn_vector).

Scope (MVP)

• Vertices only, fixed dim, cosine metric.
• No uniqueness, no edge embeddings, no cross-backend joins initially.

[sbettinzana]

Thanks for starting this discussion. I have implemented and validated a prototype of Option B on the current
JanusGraph master, using the existing mixed-index architecture and Elasticsearch as the first ANN-capable backend.
I would be interested in contributing it if the overall direction fits the project.

The main API difference from the initial suggestion is that the prototype separates threshold filtering from ranked
retrieval:

• vectorWithin() is an exact predicate for has() and returns every vector within a distance threshold;
• vectorTopK() ranks either all elements or the candidates produced by an ordinary traversal, with exact,
  approximate, and auto execution policies.

Exact evaluation is available in the JanusGraph core, so backends without ANN retain correct behavior. Strict
approximate execution requires an advertised ANN capability, while auto falls back to exact evaluation when ANN
cannot be used, including for dirty transactions. The native ANN implementation currently targets Elasticsearch 8
and 9; Elasticsearch 6/7, OpenSearch, and Cassandra SAI are not presented as supported ANN backends.

The prototype has passed the core and backend test suites, an Elasticsearch 6/7/8/9 and Java 8/11 compatibility
matrix, transaction and serialization tests, and a 1M x 1024D validation run with zero query errors and high recall.

The implementation is too large for one useful PR. I would propose starting with a small core exact-search and
capability change, followed by Elasticsearch mapping/exact support, traversal top-k, and finally ANN. I am also happy
to limit the initial MVP to vertices, cosine distance, and Elasticsearch 8+.

Would this API distinction and incremental direction make sense for JanusGraph, or would maintainers prefer to keep
top-k retrieval expressed as a knn() predicate?

I am contributing as an individual. I used OpenAI Codex to assist with implementation, review, and test automation;
I remain responsible for the design, validation, and submitted contribution.