Add hyperspacedb client by YARlabs · Pull Request #816 · zilliztech/VectorDBBench

YARlabs · 2026-07-14T11:10:25Z

Proposal: Add HyperspaceDB (`[H]`) as a new client in VectorDBBench

Summary

We'd like to contribute a new backend client for HyperspaceDB, a vector database written in Rust (project: YAR.INK), and — if the maintainers are open to it — have it evaluated on the standard leaderboard alongside the existing clients (Milvus, Qdrant, Weaviate, PgVector, etc.).

To keep the comparison fair and easy to review, this proposal is scoped to standard, well-understood ground: HNSW-based ANN search under the same L2 / Cosine metrics are already used for every other client in the leaderboard.

What we are explicitly not proposing (yet)

HyperspaceDB also implements non-Euclidean capabilities — a Lorentz/Poincaré hyperbolic index and an experimental wave-diffusion search mode. We are intentionally leaving all of that out of this PR. Reasons:

Those modes don't map onto existing MetricType/case definitions in VectorDBBench, and we don't want to ask maintainers to build new infrastructure just to evaluate us.
We want the first data point to be a clean, apples-to-apples comparison on the exact terms the benchmark already tests everyone on.
Hyperbolic/wave benchmarking can be a separate follow-up proposal once (if) the maintainers are interested, with their own metric/case definitions discussed on their own merits.

So, this PR tests HyperspaceDB purely as an HNSW vector index over L2/Cosine, competing on the same field as everyone else.

What's included in the PR

vectordb_bench/backend/clients/hyperspacedb/
- config.py — HyperspaceDBConfig(DBConfig), HyperspaceDBIndexConfig(DBCaseConfig) (HNSW params: m, ef_construction, ef_search; metric restricted to L2/COSINE for this PR)
- hyperspacedb.py — HyperspaceDB(VectorDB) implementing the standard insert/search/optimize interface
Registration of HyperspaceDB in the DB enum and db_config/db_case_config
CLI command in vectordb_bench/cli/vectordbbench.py
pyproject.toml: new hyperspacedb extra
Tests under tests/test_hyperspacedb.py following the existing client test pattern
Docs: a short usage section (connection params, install instructions, example vectordbbench hyperspacedb --help command), matching the style used for other clients

What we're asking from maintainers

Code review of the client implementation against your VectorDB interface conventions.
If the client is accepted, we understand the results on the public leaderboard require running on your standard reference client hardware (8 vCPU / 32GB, same region as the server) for consistency with the other entries. We're happy to provide a hosted or Docker-deployable instance of HyperspaceDB for that run, or to run it ourselves against your published methodology and submit results for your verification - whichever is easier on your side.
We are not asking for special-casing or a separate "non-Euclidean" leaderboard track in this PR — just a seat at the existing L2/Cosine table.

Why we think this is worth your time

We believe HyperspaceDB's HNSW implementation performs competitively against the databases currently on the leaderboard, even under the standard metrics they were designed around — that's the specific claim this PR is meant to let your benchmark verify (or refute) independently, rather than something we're asserting without your test.

Checklist

Client implements full VectorDB interface (insert, search, optimize, ready_to_load, need_normalize_cosine)
db_config / db_case_config reviewed against project conventions
CLI command added and documented
pyproject.toml extra added (hyperspacedb)
Tests included and passing
Docs updated
Open to running on maintainers' reference hardware for leaderboard inclusion

…d tune HNSW defaults

… Cosine metric calculation

… QPS

…ing for HyperspaceDB client

sre-ci-robot · 2026-07-14T11:10:29Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: YARlabs
To complete the pull request process, please assign xuanyang-cn after the PR has been reviewed.
You can assign the PR to them by writing /assign @xuanyang-cn in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

YARlabs · 2026-07-14T11:12:46Z

/assign @XuanYang-cn

XuanYang-cn · 2026-07-14T11:49:01Z

@YARlabs Please fix the github actions

XuanYang-cn

Please address the inline review comments.

XuanYang-cn · 2026-07-14T12:09:30Z

@@ -0,0 +1,4 @@
+from .config import HyperspaceDBConfig, HyperspaceDBIndexConfig
+from .hyperspacedb import HyperspaceDB


Please remove this __init__.py; the other client directories do not add one, and the existing lazy DB.init_cls registration already handles loading the adapter when needed. vectordbbench.py imports hyperspacedb.cli unconditionally, so this initializer eagerly imports the optional SDK and makes a base install fail with ModuleNotFoundError: No module named 'hyperspace' before any command can run.

XuanYang-cn · 2026-07-14T12:09:30Z

+        # Create collection
+        try:
+            metric = self.case_config.parse_metric()
+            client.create_collection(


The published SDK's create_collection() and configure() methods return False on RPC errors instead of raising, so this try block does not detect most setup failures. Please check both return values and raise when either operation fails; otherwise the benchmark proceeds without a correctly created/configured collection.

XuanYang-cn · 2026-07-14T12:09:31Z

+            metas = [{"id": str(idx)} for idx in metadata]
+
+        try:
+            self.client.batch_insert(


batch_insert() returns a boolean and returns False for RPC/server failures. Its result is ignored here, so a failed batch is reported as (len(embeddings), None) and VectorDBBench skips its retry path. Please return an error when the SDK reports False.

XuanYang-cn · 2026-07-14T12:09:31Z

+                stats = self.client.get_collection_stats(self.collection_name)
+                queue = stats.get("indexing_queue", 0)
+                count = stats.get("count", 0)
+                if queue == 0 and count > 0:


TaskRunner passes the expected dataset size through data_size, but this considers any positive count ready. That can accept a partial or stale collection as fully loaded. Please require count >= data_size; also treat empty stats as an error, because the SDK returns {} on RPC failure and the current code then polls until the one-hour timeout.

XuanYang-cn · 2026-07-14T12:09:31Z

 ]

+HyperspaceDBLoadConfig = [
+    CaseConfigParamInput_IndexType,


This generic selector exposes IVF, PQ, GPU, Flat, AUTOINDEX, and other choices, while the adapter always configures HNSW and ignores the selected index. A user can therefore publish a result labeled as a different index while actually running HNSW. Please use a HyperspaceDB-specific selector limited to HNSW, or omit the selector.

XuanYang-cn · 2026-07-14T12:09:31Z

@@ -0,0 +1,794 @@
+{


Please remove this file and the other two HyperspaceDB result files. We do not accept benchmark results generated by contributors into the repository. You are welcome to paste these results in the PR comments for others' reference, but we only merge results tested by maintainers in our own test environment.

XuanYang-cn · 2026-07-14T12:09:31Z

+    ]
+    ef_construction: Annotated[
+        int,
+        click.option("--ef-construction", type=int, help="HNSW efConstruction", default=100),


This defaults ef_construction to 100, while HyperspaceDBIndexConfig and the UI default it to 200. The same benchmark therefore changes depending on whether it is started through CLI or UI. Please define and reuse one default.

XuanYang-cn · 2026-07-14T12:09:31Z

 | lindorm                  | `pip install vectordb-bench[lindorm]`       |
 | volc_mysql               | `pip install vectordb-bench[volc_mysql]`    |
 | adbpg                    | `pip install vectordb-bench[adbpg]`         |
+| hyperspacedb             | `pip install vectordb-bench[hyperspacedb]`  |


The PR description promises a short usage section with connection parameters and an example vectordbbench hyperspacedb --help command, but this only adds the installation row. Please document --host, optional --api-key, and a minimal CLI example.

XuanYang-cn · 2026-07-14T12:09:31Z

+        self.client.close()
+        self.client = None
+
+    def ready_to_search(self) -> bool:


This method is not part of the current VectorDB readiness API and always returns None. Meanwhile, the PR checklist promises a readiness implementation. Please remove this dead method or implement the current readiness hook, such as poll_insert_readiness(), and update the checklist accordingly.

beeqb added 6 commits July 8, 2026 12:08

feat: add HyperspaceDB client adapter

2a77fdb

feat: add CLI support, unit tests, and documentation for HyperspaceDB

fdc197d

fix: restore indexing queue wait in optimize via gRPC client stats an…

30eaa20

…d tune HNSW defaults

fix: set pool_size to 64 and enable need_normalize_cosine for correct…

ebe5439

… Cosine metric calculation

perf: implement direct gRPC fast-path in search_embedding to maximize…

9424f7c

… QPS

feat: Add support for filter operations and fix HNSW M parameter pass…

c2d0738

…ing for HyperspaceDB client

XuanYang-cn requested changes Jul 14, 2026

View reviewed changes

		@@ -0,0 +1,4 @@
		from .config import HyperspaceDBConfig, HyperspaceDBIndexConfig
		from .hyperspacedb import HyperspaceDB

Uh oh!

Conversation

YARlabs commented Jul 14, 2026

Proposal: Add HyperspaceDB ([H]) as a new client in VectorDBBench

Summary

What we are explicitly not proposing (yet)

What's included in the PR

What we're asking from maintainers

Why we think this is worth your time

Checklist

Uh oh!

sre-ci-robot commented Jul 14, 2026

Uh oh!

YARlabs commented Jul 14, 2026

Uh oh!

XuanYang-cn commented Jul 14, 2026

Uh oh!

XuanYang-cn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Proposal: Add HyperspaceDB (`[H]`) as a new client in VectorDBBench