feat: add VectorChord client implementation and configuration 🎉

- Introduced VectorChord client with support for embedding operations.
- Added configuration classes for VectorChord settings and parameters.

Author: R3gardless

vectordb_bench/backend/clients/vectorchord/__init__.py

@@ -0,0 +1,160 @@
+import os
+from typing import Annotated, Unpack
+
+import click
+from pydantic import SecretStr
+
+from vectordb_bench.backend.clients import DB
+
+from ....cli.cli import (
+    CommonTypedDict,
+    cli,
+    click_parameter_decorators_from_typed_dict,
+    run,
+)
+
+
+class VectorChordTypedDict(CommonTypedDict):
+    user_name: Annotated[
+        str,
+        click.option("--user-name", type=str, help="Db username", required=True),
+    ]
+    password: Annotated[
+        str,
+        click.option(
+            "--password",
+            type=str,
+            help="Postgres database password",
+            default=lambda: os.environ.get("POSTGRES_PASSWORD", ""),
+            show_default="$POSTGRES_PASSWORD",
+        ),
+    ]
+
+    host: Annotated[str, click.option("--host", type=str, help="Db host", required=True)]
+    port: Annotated[
+        int,
+        click.option(
+            "--port",
+            type=int,
+            help="Postgres database port",
+            default=5432,
+            show_default=True,
+            required=False,
+        ),
+    ]
+    db_name: Annotated[str, click.option("--db-name", type=str, help="Db name", required=True)]
+
+
+class VectorChordRQTypedDict(VectorChordTypedDict):
+    lists: Annotated[
+        int | None,
+        click.option(
+            "--lists",
+            type=int,
+            help="Number of IVF lists for vchordrq index",
+        ),
+    ]
+    probes: Annotated[
+        int | None,
+        click.option(
+            "--probes",
+            type=int,
+            help="Number of probes during search",
+            default=10,
+            show_default=True,
+        ),
+    ]
+    epsilon: Annotated[
+        float | None,
+        click.option(
+            "--epsilon",
+            type=float,
+            help="Reranking precision factor (0.0-4.0, higher is more accurate but slower)",
+            default=1.9,
+            show_default=True,
+        ),
+    ]
+    residual_quantization: Annotated[
+        bool,
+        click.option(
+            "--residual-quantization/--no-residual-quantization",
+            type=bool,
+            help="Enable residual quantization for improved accuracy",
+            default=False,
+            show_default=True,
+        ),
+    ]
+    spherical_centroids: Annotated[
+        bool,
+        click.option(
+            "--spherical-centroids/--no-spherical-centroids",
+            type=bool,
+            help="L2-normalize centroids during K-means (recommended for cosine/IP)",
+            default=False,
+            show_default=True,
+        ),
+    ]
+    build_threads: Annotated[
+        int | None,
+        click.option(
+            "--build-threads",
+            type=int,
+            help="Number of threads for index building (range: 1-255)",
+        ),
+    ]
+    degree_of_parallelism: Annotated[
+        int | None,
+        click.option(
+            "--degree-of-parallelism",
+            type=int,
+            help="Degree of parallelism for index build (range: 1-256, default: 32)",
+        ),
+    ]
+    max_scan_tuples: Annotated[
+        int | None,
+        click.option(
+            "--max-scan-tuples",
+            type=int,
+            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()
+@click_parameter_decorators_from_typed_dict(VectorChordRQTypedDict)
+def VectorChordRQ(
+    **parameters: Unpack[VectorChordRQTypedDict],
+):
+    from .config import VectorChordConfig, VectorChordRQConfig
+
+    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=VectorChordRQConfig(
+            lists=parameters["lists"],
+            probes=parameters["probes"],
+            epsilon=parameters["epsilon"],
+            residual_quantization=parameters["residual_quantization"],
+            spherical_centroids=parameters["spherical_centroids"],
+            build_threads=parameters["build_threads"],
+            degree_of_parallelism=parameters["degree_of_parallelism"],
+            max_scan_tuples=parameters["max_scan_tuples"],
+            max_parallel_workers=parameters["max_parallel_workers"],
+        ),
+        **parameters,
+    )

vectordb_bench/backend/clients/vectorchord/cli.py

@@ -0,0 +1,123 @@
+from abc import abstractmethod
+from typing import LiteralString, TypedDict
+
+from pydantic import BaseModel, SecretStr
+
+from ..api import DBCaseConfig, DBConfig, IndexType, MetricType
+
+
+class VectorChordConfigDict(TypedDict):
+    """These keys will be directly used as kwargs in psycopg connection string,
+    so the names must match exactly psycopg API"""
+
+    user: str
+    password: str
+    host: str
+    port: int
+    dbname: str
+
+
+class VectorChordConfig(DBConfig):
+    user_name: SecretStr = SecretStr("postgres")
+    password: SecretStr
+    host: str = "localhost"
+    port: int = 5432
+    db_name: str = "vectordb"
+
+    def to_dict(self) -> VectorChordConfigDict:
+        user_str = self.user_name.get_secret_value()
+        pwd_str = self.password.get_secret_value()
+        return {
+            "host": self.host,
+            "port": self.port,
+            "dbname": self.db_name,
+            "user": user_str,
+            "password": pwd_str,
+        }
+
+
+class VectorChordIndexConfig(BaseModel, DBCaseConfig):
+    metric_type: MetricType | None = None
+    create_index_before_load: bool = False
+    create_index_after_load: bool = True
+
+    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"
+
+    def parse_metric_fun_op(self) -> LiteralString:
+        if self.metric_type == MetricType.L2:
+            return "<->"
+        if self.metric_type == MetricType.IP:
+            return "<#>"
+        return "<=>"
+
+    @abstractmethod
+    def index_param(self) -> dict: ...
+
+    @abstractmethod
+    def search_param(self) -> dict: ...
+
+    @abstractmethod
+    def session_param(self) -> dict: ...
+
+
+class VectorChordRQConfig(VectorChordIndexConfig):
+    index: IndexType = IndexType.VCHORDRQ
+    # Build parameters (top-level options)
+    residual_quantization: bool = False
+    degree_of_parallelism: int | None = None  # default 32, range [1, 256]
+    # Build parameters ([build.internal] section)
+    lists: int | None = None
+    spherical_centroids: bool = False
+    build_threads: int | None = None  # range [1, 255]
+    # PostgreSQL tuning parameter
+    max_parallel_workers: int | None = None  # sets max_parallel_workers & max_parallel_maintenance_workers
+    # Search parameters (GUCs)
+    probes: int | None = 10
+    epsilon: float | None = 1.9  # range [0.0, 4.0]
+    max_scan_tuples: int | None = None  # default -1, range [-1, 2147483647]
+
+    def index_param(self) -> dict:
+        options_parts = []
+        if self.residual_quantization:
+            options_parts.append("residual_quantization = true")
+        if self.degree_of_parallelism is not None:
+            options_parts.append(f"degree_of_parallelism = {self.degree_of_parallelism}")
+        options_parts.append("[build.internal]")
+        if self.lists is not None:
+            options_parts.append(f"lists = [{self.lists}]")
+        if self.spherical_centroids:
+            options_parts.append("spherical_centroids = true")
+        if self.build_threads is not None:
+            options_parts.append(f"build_threads = {self.build_threads}")
+
+        return {
+            "metric": self.parse_metric(),
+            "index_type": self.index.value,
+            "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.probes is not None:
+            params["vchordrq.probes"] = str(self.probes)
+        if self.epsilon is not None:
+            params["vchordrq.epsilon"] = str(self.epsilon)
+        if self.max_scan_tuples is not None:
+            params["vchordrq.max_scan_tuples"] = str(self.max_scan_tuples)
+        return params
+
+
+_vectorchord_case_config = {
+    IndexType.VCHORDRQ: VectorChordRQConfig,
+}