feat: add VectorChordGraph support and configuration 🎉✨

R3gardless · R3gardless · commit 27c5f54ffdc2 · 2026-04-02T23:41:42.000+09:00
- Introduced VectorChordGraph command to CLI for enhanced functionality.
- Added quantization and reranking options to VectorChord configurations.
diff --git a/vectordb_bench/backend/clients/api.py b/vectordb_bench/backend/clients/api.py
@@ -43,6 +43,7 @@ class IndexType(StrEnum):
     GPU_CAGRA = "GPU_CAGRA"
     SCANN = "scann"
     VCHORDRQ = "vchordrq"
+    VCHORDG = "vchordg"
     SCANN_MILVUS = "SCANN_MILVUS"
     Hologres_HGraph = "HGraph"
     Hologres_Graph = "Graph"
diff --git a/vectordb_bench/backend/clients/vectorchord/cli.py b/vectordb_bench/backend/clients/vectorchord/cli.py
@@ -43,6 +43,25 @@ class VectorChordTypedDict(CommonTypedDict):
         ),
     ]
     db_name: Annotated[str, click.option("--db-name", type=str, help="Db name", required=True)]
+    max_parallel_workers: Annotated[
+        int | None,
+        click.option(
+            "--max-parallel-workers",
+            type=int,
+            help="Sets the maximum number of parallel workers for index creation",
+            required=False,
+        ),
+    ]
+    quantization_type: Annotated[
+        str | None,
+        click.option(
+            "--quantization-type",
+            type=click.Choice(["vector", "halfvec", "rabitq8", "rabitq4"]),
+            help="Quantization type for vectors",
+            default="vector",
+            show_default=True,
+        ),
+    ]
 
 
 class VectorChordRQTypedDict(VectorChordTypedDict):
@@ -84,6 +103,16 @@ class VectorChordRQTypedDict(VectorChordTypedDict):
             show_default=True,
         ),
     ]
+    rerank_in_table: Annotated[
+        bool,
+        click.option(
+            "--rerank-in-table/--no-rerank-in-table",
+            type=bool,
+            help="Read vectors from table instead of storing in index (saves storage, degrades query performance)",
+            default=False,
+            show_default=True,
+        ),
+    ]
     spherical_centroids: Annotated[
         bool,
         click.option(
@@ -118,14 +147,6 @@ class VectorChordRQTypedDict(VectorChordTypedDict):
             help="Max tuples to scan before stopping (-1 for unlimited)",
         ),
     ]
-    max_parallel_workers: Annotated[
-        int | None,
-        click.option(
-            "--max-parallel-workers",
-            type=int,
-            help="Sets the maximum number of parallel workers for index creation",
-        ),
-    ]
 
 
 @cli.command()
@@ -146,10 +167,12 @@ def VectorChordRQ(
             db_name=parameters["db_name"],
         ),
         db_case_config=VectorChordRQConfig(
+            quantization_type=parameters["quantization_type"],
             lists=parameters["lists"],
             probes=parameters["probes"],
             epsilon=parameters["epsilon"],
             residual_quantization=parameters["residual_quantization"],
+            rerank_in_table=parameters["rerank_in_table"],
             spherical_centroids=parameters["spherical_centroids"],
             build_threads=parameters["build_threads"],
             degree_of_parallelism=parameters["degree_of_parallelism"],
@@ -158,3 +181,78 @@ def VectorChordRQ(
         ),
         **parameters,
     )
+
+
+class VectorChordGraphTypedDict(VectorChordTypedDict):
+    m: Annotated[
+        int | None,
+        click.option(
+            "--m",
+            type=int,
+            help="Max neighbors per vertex (default: 32)",
+        ),
+    ]
+    ef_construction: Annotated[
+        int | None,
+        click.option(
+            "--ef-construction",
+            type=int,
+            help="Dynamic list size during insertion (default: 64)",
+        ),
+    ]
+    bits: Annotated[
+        int | None,
+        click.option(
+            "--bits",
+            type=int,
+            help="RaBitQ quantization ratio (1 or 2, default: 2)",
+        ),
+    ]
+    ef_search: Annotated[
+        int | None,
+        click.option(
+            "--ef-search",
+            type=int,
+            help="Dynamic list size for search (default: 64)",
+            default=64,
+            show_default=True,
+        ),
+    ]
+    beam_search: Annotated[
+        int | None,
+        click.option(
+            "--beam-search",
+            type=int,
+            help="Batch vertex access width during search (default: 1)",
+        ),
+    ]
+
+
+@cli.command()
+@click_parameter_decorators_from_typed_dict(VectorChordGraphTypedDict)
+def VectorChordGraph(
+    **parameters: Unpack[VectorChordGraphTypedDict],
+):
+    from .config import VectorChordConfig, VectorChordGraphConfig
+
+    run(
+        db=DB.VectorChord,
+        db_config=VectorChordConfig(
+            db_label=parameters["db_label"],
+            user_name=SecretStr(parameters["user_name"]),
+            password=SecretStr(parameters["password"]),
+            host=parameters["host"],
+            port=parameters["port"],
+            db_name=parameters["db_name"],
+        ),
+        db_case_config=VectorChordGraphConfig(
+            quantization_type=parameters["quantization_type"],
+            m=parameters["m"],
+            ef_construction=parameters["ef_construction"],
+            bits=parameters["bits"],
+            ef_search=parameters["ef_search"],
+            beam_search=parameters["beam_search"],
+            max_parallel_workers=parameters["max_parallel_workers"],
+        ),
+        **parameters,
+    )
diff --git a/vectordb_bench/backend/clients/vectorchord/config.py b/vectordb_bench/backend/clients/vectorchord/config.py
@@ -36,17 +36,39 @@ def to_dict(self) -> VectorChordConfigDict:
         }
 
 
+_METRIC_OPS = {
+    "vector": {
+        MetricType.L2: "vector_l2_ops",
+        MetricType.IP: "vector_ip_ops",
+        MetricType.COSINE: "vector_cosine_ops",
+    },
+    "halfvec": {
+        MetricType.L2: "halfvec_l2_ops",
+        MetricType.IP: "halfvec_ip_ops",
+        MetricType.COSINE: "halfvec_cosine_ops",
+    },
+    "rabitq8": {
+        MetricType.L2: "rabitq8_l2_ops",
+        MetricType.IP: "rabitq8_ip_ops",
+        MetricType.COSINE: "rabitq8_cosine_ops",
+    },
+    "rabitq4": {
+        MetricType.L2: "rabitq4_l2_ops",
+        MetricType.IP: "rabitq4_ip_ops",
+        MetricType.COSINE: "rabitq4_cosine_ops",
+    },
+}
+
+
 class VectorChordIndexConfig(BaseModel, DBCaseConfig):
     metric_type: MetricType | None = None
     create_index_before_load: bool = False
     create_index_after_load: bool = True
+    quantization_type: str = "vector"  # vector, halfvec, rabitq8, rabitq4
 
     def parse_metric(self) -> str:
-        if self.metric_type == MetricType.L2:
-            return "vector_l2_ops"
-        if self.metric_type == MetricType.IP:
-            return "vector_ip_ops"
-        return "vector_cosine_ops"
+        ops = _METRIC_OPS.get(self.quantization_type, _METRIC_OPS["vector"])
+        return ops.get(self.metric_type, ops[MetricType.COSINE])
 
     def parse_metric_fun_op(self) -> LiteralString:
         if self.metric_type == MetricType.L2:
@@ -69,6 +91,7 @@ class VectorChordRQConfig(VectorChordIndexConfig):
     index: IndexType = IndexType.VCHORDRQ
     # Build parameters (top-level options)
     residual_quantization: bool = False
+    rerank_in_table: bool = False
     degree_of_parallelism: int | None = None  # default 32, range [1, 256]
     # Build parameters ([build.internal] section)
     lists: int | None = None
@@ -83,6 +106,8 @@ class VectorChordRQConfig(VectorChordIndexConfig):
 
     def index_param(self) -> dict:
         options_parts = []
+        if self.rerank_in_table:
+            options_parts.append("rerank_in_table = true")
         if self.residual_quantization:
             options_parts.append("residual_quantization = true")
         if self.degree_of_parallelism is not None:
@@ -98,6 +123,7 @@ def index_param(self) -> dict:
         return {
             "metric": self.parse_metric(),
             "index_type": self.index.value,
+            "quantization_type": self.quantization_type,
             "options": "\n".join(options_parts),
             "max_parallel_workers": self.max_parallel_workers,
         }
@@ -118,6 +144,50 @@ def session_param(self) -> dict:
         return params
 
 
+class VectorChordGraphConfig(VectorChordIndexConfig):
+    index: IndexType = IndexType.VCHORDG
+    # Build parameters
+    m: int | None = None  # default 32, max neighbors per vertex
+    ef_construction: int | None = None  # default 64
+    bits: int | None = None  # default 2, quantization ratio (1 or 2)
+    # PostgreSQL tuning parameter
+    max_parallel_workers: int | None = None
+    # Search parameters (GUCs)
+    ef_search: int | None = 64  # range [1, 65535]
+    beam_search: int | None = None  # default 1
+
+    def index_param(self) -> dict:
+        options_parts = []
+        if self.m is not None:
+            options_parts.append(f"m = {self.m}")
+        if self.ef_construction is not None:
+            options_parts.append(f"ef_construction = {self.ef_construction}")
+        if self.bits is not None:
+            options_parts.append(f"bits = {self.bits}")
+
+        return {
+            "metric": self.parse_metric(),
+            "index_type": self.index.value,
+            "quantization_type": self.quantization_type,
+            "options": "\n".join(options_parts),
+            "max_parallel_workers": self.max_parallel_workers,
+        }
+
+    def search_param(self) -> dict:
+        return {
+            "metric_fun_op": self.parse_metric_fun_op(),
+        }
+
+    def session_param(self) -> dict:
+        params = {}
+        if self.ef_search is not None:
+            params["vchordg.ef_search"] = str(self.ef_search)
+        if self.beam_search is not None:
+            params["vchordg.beam_search"] = str(self.beam_search)
+        return params
+
+
 _vectorchord_case_config = {
     IndexType.VCHORDRQ: VectorChordRQConfig,
+    IndexType.VCHORDG: VectorChordGraphConfig,
 }
diff --git a/vectordb_bench/backend/clients/vectorchord/vectorchord.py b/vectordb_bench/backend/clients/vectorchord/vectorchord.py
@@ -44,6 +44,10 @@ def __init__(
         self._primary_field = "id"
         self._vector_field = "embedding"
 
+        index_param = self.case_config.index_param()
+        self._quantization_type = index_param["quantization_type"]
+        self._index_method = index_param["index_type"]
+
         self.conn, self.cursor = self._create_connection(**self.db_config)
 
         log.info(f"{self.name} config values: {self.db_config}\n{self.case_config}")
@@ -103,13 +107,16 @@ def init(self) -> Generator[None, None, None]:
                 self.cursor.execute(command)
             self.conn.commit()
 
+        # Search query cast type: rabitq8/rabitq4 queries still accept ::vector input
+        cast_type = "vector"
+
         self._filtered_search = sql.Composed(
             [
                 sql.SQL("SELECT id FROM public.{} WHERE id >= %s ORDER BY embedding ").format(
                     sql.Identifier(self.table_name),
                 ),
                 sql.SQL(self.case_config.search_param()["metric_fun_op"]),
-                sql.SQL(" %s::vector LIMIT %s::int"),
+                sql.SQL(f" %s::{cast_type} LIMIT %s::int"),
             ],
         )
 
@@ -119,7 +126,7 @@ def init(self) -> Generator[None, None, None]:
                     sql.Identifier(self.table_name),
                 ),
                 sql.SQL(self.case_config.search_param()["metric_fun_op"]),
-                sql.SQL(" %s::vector LIMIT %s::int"),
+                sql.SQL(f" %s::{cast_type} LIMIT %s::int"),
             ],
         )
 
@@ -204,18 +211,19 @@ def _create_index(self):
         index_create_sql = sql.SQL(
             """
             CREATE INDEX IF NOT EXISTS {index_name} ON public.{table_name}
-            USING vchordrq (embedding {embedding_metric})
+            USING {index_method} (embedding {embedding_metric})
             """,
         ).format(
             index_name=sql.Identifier(self._index_name),
             table_name=sql.Identifier(self.table_name),
+            index_method=sql.SQL(self._index_method),
             embedding_metric=sql.Identifier(index_param["metric"]),
         )
 
         options_str = index_param.get("options", "")
         if options_str:
             with_clause = sql.SQL(
-                "WITH (options = $vchordrq$\n{options}\n$vchordrq$);",
+                "WITH (options = $vchord$\n{options}\n$vchord$);",
             ).format(options=sql.SQL(options_str))
         else:
             with_clause = sql.SQL(";")
@@ -232,10 +240,20 @@ def _create_table(self, dim: int):
         try:
             log.info(f"{self.name} client create table : {self.table_name}")
 
+            col_type = self._quantization_type
+            if col_type in ("rabitq8", "rabitq4"):
+                # rabitq types need vector column + quantization during insert
+                col_type = "vector"
+
             self.cursor.execute(
                 sql.SQL(
-                    "CREATE TABLE IF NOT EXISTS public.{table_name} (id BIGINT PRIMARY KEY, embedding vector({dim}));",
-                ).format(table_name=sql.Identifier(self.table_name), dim=dim),
+                    "CREATE TABLE IF NOT EXISTS public.{table_name} "
+                    "(id BIGINT PRIMARY KEY, embedding {col_type}({dim}));",
+                ).format(
+                    table_name=sql.Identifier(self.table_name),
+                    col_type=sql.SQL(col_type),
+                    dim=dim,
+                ),
             )
             self.conn.commit()
         except Exception as e:
@@ -255,14 +273,25 @@ def insert_embeddings(
             metadata_arr = np.array(metadata)
             embeddings_arr = np.array(embeddings)
 
-            with self.cursor.copy(
-                sql.SQL("COPY public.{table_name} FROM STDIN (FORMAT BINARY)").format(
-                    table_name=sql.Identifier(self.table_name),
-                ),
-            ) as copy:
-                copy.set_types(["bigint", "vector"])
-                for i, row in enumerate(metadata_arr):
-                    copy.write_row((row, embeddings_arr[i]))
+            if self._quantization_type == "halfvec":
+                with self.cursor.copy(
+                    sql.SQL("COPY public.{table_name} FROM STDIN (FORMAT BINARY)").format(
+                        table_name=sql.Identifier(self.table_name),
+                    ),
+                ) as copy:
+                    copy.set_types(["bigint", "halfvec"])
+                    for i, row in enumerate(metadata_arr):
+                        copy.write_row((row, np.float16(embeddings_arr[i])))
+            else:
+                # vector, rabitq8, rabitq4 all store as vector column
+                with self.cursor.copy(
+                    sql.SQL("COPY public.{table_name} FROM STDIN (FORMAT BINARY)").format(
+                        table_name=sql.Identifier(self.table_name),
+                    ),
+                ) as copy:
+                    copy.set_types(["bigint", "vector"])
+                    for i, row in enumerate(metadata_arr):
+                        copy.write_row((row, embeddings_arr[i]))
             self.conn.commit()
 
             return len(metadata), None
diff --git a/vectordb_bench/cli/vectordbbench.py b/vectordb_bench/cli/vectordbbench.py
