feat: native vector search support (paradedb/paradedb#5685)

Author: rebasedming

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format
 
 ## Unreleased
 
+### Added
+
+- Native vector search support: a `Vector(n)` column type, `VectorField` for declaring pgvector columns with a distance metric (`l2`, `cosine`, `ip`) inside BM25 indexes, and `vector.l2_distance` / `vector.cosine_distance` / `vector.inner_product` query expressions for Top-K ordering. Alembic autogenerate round-trips BM25 indexes containing vector opclasses without churn.
+
 ## [0.8.0] - 2026-07-14
 
 ### Changed

README.md

@@ -47,6 +47,48 @@ The official [SQLAlchemy](https://www.sqlalchemy.org/) integration for [ParadeDB
 | ParadeDB   | 0.22.0+                       |
 | PostgreSQL | 15+ (with ParadeDB extension) |
 
+## Vector Search
+
+ParadeDB indexes pgvector `vector` columns directly inside BM25 indexes, so no pgvector ORM library is needed. Declare a `vector(n)` column with the built-in `Vector` type, add it to the BM25 index with `VectorField` and a distance metric, and order by the matching distance function:
+
+```python
+from sqlalchemy import Index, select
+from paradedb.sqlalchemy import search, vector
+from paradedb.sqlalchemy.indexing import BM25Field, VectorField
+from paradedb.sqlalchemy.vector import Vector
+
+
+class Product(Base):
+    __tablename__ = "products"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    embedding: Mapped[list[float]] = mapped_column(Vector(3), nullable=False)
+
+
+Index(
+    "products_bm25_idx",
+    BM25Field(Product.id),
+    BM25Field(Product.description),
+    VectorField(Product.embedding, metric="l2"),  # metric: "l2" (default), "cosine", or "ip"
+    postgresql_using="bm25",
+    postgresql_with={"key_field": "id"},
+)
+
+# Top-K query: a @@@ predicate (e.g. search.all) and a LIMIT are required
+# for index pushdown. A pure vector query uses the match-all predicate.
+stmt = (
+    select(Product.id)
+    .where(search.all(Product.id))
+    .order_by(vector.l2_distance(Product.embedding, [1.0, 0.0, 0.0]))
+    .limit(10)
+)
+```
+
+The ORDER BY distance function must match the index metric: `vector.l2_distance` (`<->`) with `metric="l2"`, `vector.cosine_distance` (`<=>`) with `metric="cosine"`, and `vector.inner_product` (`<#>`) with `metric="ip"`. A mismatched pair still returns correct results but silently loses Top-K index pushdown.
+
+Vector search requires a ParadeDB build with vector-in-bm25 support and the `vector` (pgvector) extension installed.
+
 ## Examples
 
 - [Quick Start](examples/quickstart/quickstart.py)
@@ -55,6 +97,7 @@ The official [SQLAlchemy](https://www.sqlalchemy.org/) integration for [ParadeDB
 - [More Like This](examples/more_like_this/more_like_this.py)
 - [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.py)
 - [RAG](examples/rag/rag.py)
+- [Vector Search](examples/vector_search/vector_search.py)
 
 ## Contributing
 

examples/vector_search/setup.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+
+from sqlalchemy import Index, Integer, Text, create_engine, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+
+from paradedb.sqlalchemy import indexing
+from paradedb.sqlalchemy.vector import Vector
+
+
+PRODUCT_ROWS = [
+    {"id": 1, "description": "Sleek running shoes for daily training", "embedding": [1, 0, 0]},
+    {"id": 2, "description": "Trail running shoes with durable grip", "embedding": [0.9, 0.1, 0]},
+    {"id": 3, "description": "Wireless noise-canceling headphones", "embedding": [0, 1, 0]},
+    {"id": 4, "description": "Artistic ceramic vase", "embedding": [0, 0, 1]},
+]
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Product(Base):
+    __tablename__ = "vector_products"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    embedding: Mapped[list[float]] = mapped_column(Vector(3), nullable=False)
+
+
+Index(
+    "vector_products_bm25_idx",
+    indexing.BM25Field(Product.id),
+    indexing.BM25Field(Product.description),
+    indexing.VectorField(Product.embedding, metric="l2"),
+    postgresql_using="bm25",
+    postgresql_with={"key_field": "id"},
+)
+
+
+def engine_from_env() -> Engine:
+    dsn = os.getenv("DATABASE_URL", "postgresql+psycopg://postgres:postgres@localhost:5443/postgres")
+    return create_engine(dsn)
+
+
+def setup_database(engine: Engine) -> None:
+    with engine.begin() as conn:
+        conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
+    Base.metadata.drop_all(engine)
+    Base.metadata.create_all(engine)
+    with Session(engine) as session:
+        session.add_all(Product(**row) for row in PRODUCT_ROWS)
+        session.commit()

examples/vector_search/vector_search.py

@@ -0,0 +1,37 @@
+"""Top-K vector search over a BM25 index.
+
+Requires a ParadeDB build with vector-in-bm25 support (pg_search branch
+``mvp/vector-search``). The ORDER BY metric must match the index opclass
+metric, the ``@@@`` predicate (here ``search.all``) is mandatory, and a
+LIMIT is required for Top-K index pushdown.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from paradedb.sqlalchemy import search, vector
+from setup import Product, engine_from_env, setup_database
+
+
+def main() -> None:
+    engine = engine_from_env()
+    setup_database(engine)
+
+    query_embedding = [1.0, 0.0, 0.0]
+
+    stmt = (
+        select(Product.id, Product.description)
+        .where(search.all(Product.id))
+        .order_by(vector.l2_distance(Product.embedding, query_embedding))
+        .limit(2)
+    )
+
+    with Session(engine) as session:
+        for row in session.execute(stmt):
+            print(dict(row._mapping))
+
+
+if __name__ == "__main__":
+    main()

paradedb/__init__.py

@@ -6,8 +6,9 @@
     paradedb_verify_index,
 )
 from .sqlalchemy.facets import with_rows
-from .sqlalchemy.indexing import BM25Field, assert_indexed, describe
+from .sqlalchemy.indexing import BM25Field, VectorField, assert_indexed, describe
 from .sqlalchemy.tokenizer import Tokenizer
+from .sqlalchemy.vector import Vector, cosine_distance, inner_product, l2_distance
 from .sqlalchemy import tokenizer
 from .sqlalchemy.pdb import agg, alias, score, snippet, snippet_positions, snippets
 from .sqlalchemy.search import (
@@ -34,12 +35,17 @@
     "BM25Field",
     "ProximityExpr",
     "Tokenizer",
+    "Vector",
+    "VectorField",
     "agg",
     "alias",
     "all",
     "assert_indexed",
+    "cosine_distance",
     "describe",
     "exists",
+    "inner_product",
+    "l2_distance",
     "match_all",
     "match_any",
     "more_like_this",

paradedb/sqlalchemy/__init__.py

@@ -1,3 +1,14 @@
-from . import diagnostics, expr, facets, indexing, tokenizer, inspect, pdb, search, select_with
+from . import diagnostics, expr, facets, indexing, tokenizer, inspect, pdb, search, select_with, vector
 
-__all__ = ["diagnostics", "expr", "facets", "indexing", "tokenizer", "inspect", "pdb", "search", "select_with"]
+__all__ = [
+    "diagnostics",
+    "expr",
+    "facets",
+    "indexing",
+    "tokenizer",
+    "inspect",
+    "pdb",
+    "search",
+    "select_with",
+    "vector",
+]

paradedb/sqlalchemy/alembic.py

@@ -231,7 +231,9 @@ def _autogen_bm25_meta_indexes(
 def _autogen_bm25_db_indexes(conn, effective_schemas: set[str]) -> dict[tuple[str, str], dict]:
     """Return {(schema, index_name): {table_name, expressions, key_field, where}} from pg_indexes."""
     from .indexing import (
+        _extract_bm25_field_list,
         _extract_key_field,
+        _extract_trailing_opclass,
         _extract_where_clause,
         _introspect_bm25_index_rows,
         _normalize_reloption_value,
@@ -251,7 +253,16 @@ def _autogen_bm25_db_indexes(conn, effective_schemas: set[str]) -> dict[tuple[st
                     "where": _extract_where_clause(str(row["indexdef"])),
                 },
             )
-            index_entry["expressions"].append(str(row["keydef"]))
+            # pg_get_indexdef(oid, colno, true) omits opclasses, so recover any
+            # vector opclass from the full index definition's field list.
+            expression = str(row["keydef"])
+            field_list = _extract_bm25_field_list(str(row["indexdef"]))
+            position = len(index_entry["expressions"])
+            if position < len(field_list) and _extract_trailing_opclass(expression) is None:
+                opclass = _extract_trailing_opclass(field_list[position])
+                if opclass is not None:
+                    expression = f"{expression} {opclass}"
+            index_entry["expressions"].append(expression)
             if not index_entry["key_field"]:
                 index_entry["key_field"] = _extract_key_field(str(row["indexdef"])) or ""
     return result
@@ -285,9 +296,14 @@ def _strip_match(match: re.Match[str]) -> str:
     return qualifier_re.sub(_strip_match, expr)
 
 
+_DEFAULT_VECTOR_OPCLASS_RE = re.compile(r"\s+vector_l2_ops\s*$")
+
+
 def _normalize_bm25_expression(expr: str) -> str:
     """Normalize BM25 expression text to reduce false-positive autogen churn."""
-    normalized = "".join(expr.split())
+    # vector_l2_ops is the default opclass, so Postgres omits it from indexdef.
+    normalized = _DEFAULT_VECTOR_OPCLASS_RE.sub("", expr)
+    normalized = "".join(normalized.split())
     normalized = normalized.replace('"', "")
     normalized = normalized.replace("::text", "")
     return _strip_non_pdb_qualifiers(normalized)

paradedb/sqlalchemy/indexing.py

@@ -15,6 +15,7 @@
 
 from ._select_introspection import has_limit, has_order_by
 from ._pdb_cast import PDBCast
+from .vector import VECTOR_OPCLASSES
 from .errors import (
     DuplicateTokenizerAliasError,
     FieldNotIndexedError,
@@ -58,6 +59,36 @@ def _compile_bm25_field_default(element: BM25Field, compiler, **kw: Any) -> str:
     raise CompileError("BM25Field is only supported for PostgreSQL dialects")
 
 
+class VectorField(BM25Field):
+    """Represents a pgvector column in a ParadeDB BM25 index with a distance metric opclass."""
+
+    inherit_cache = True
+    _traverse_internals = [
+        ("expr", InternalTraversal.dp_clauseelement),
+        ("metric", InternalTraversal.dp_string),
+    ]
+
+    def __init__(self, expr: ClauseElement, *, metric: str = "l2") -> None:
+        if metric not in VECTOR_OPCLASSES:
+            raise InvalidArgumentError(f"metric must be one of: {', '.join(sorted(VECTOR_OPCLASSES))}")
+        super().__init__(expr)
+        self.metric = metric
+
+    @property
+    def opclass(self) -> str:
+        return VECTOR_OPCLASSES[self.metric]
+
+
+@compiles(VectorField, "postgresql")
+def _compile_vector_field(element: VectorField, compiler, **kw: Any) -> str:
+    return f"{compiler.process(element.expr, **kw)} {element.opclass}"
+
+
+@compiles(VectorField)
+def _compile_vector_field_default(element: VectorField, compiler, **kw: Any) -> str:
+    raise CompileError("VectorField is only supported for PostgreSQL dialects")
+
+
 def _is_bm25_index(index: Index) -> bool:
     using = index.dialect_options["postgresql"].get("using")
     return bool(using and str(using).lower() == "bm25")
@@ -110,6 +141,8 @@ def validate_bm25_index(index: Index) -> None:
         raise InvalidKeyFieldError(f"BM25 key_field '{key_field}' must be the first indexed BM25Field")
     if first_field.tokenizer is not None:
         raise InvalidKeyFieldError(f"BM25 key_field '{key_field}' must be untokenized")
+    if isinstance(first_field, VectorField):
+        raise InvalidKeyFieldError(f"BM25 key_field '{key_field}' cannot be a VectorField")
 
 
 @event.listens_for(Index, "before_create")
@@ -128,6 +161,7 @@ class IndexMeta:
 
 
 _KEY_FIELD_RE = re.compile(r"key_field\s*=\s*'?\"?([^'\",)\s]+)\"?'?", re.IGNORECASE)
+_VECTOR_OPCLASS_TAIL_RE = re.compile(r"\s(vector_(?:l2|cosine|ip)_ops)\s*$")
 _ALIAS_RE = re.compile(r"alias\s*=\s*([A-Za-z_][A-Za-z0-9_]*)", re.IGNORECASE)
 _TOKENIZER_NAME_RE = re.compile(r"::pdb\.([A-Za-z_][A-Za-z0-9_]*)", re.IGNORECASE)
 _IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
@@ -271,6 +305,13 @@ def _extract_where_clause(indexdef: str) -> str | None:
     return None
 
 
+def _extract_trailing_opclass(field_expr: str) -> str | None:
+    """Return the trailing vector opclass token from an index field expression, e.g.
+    ``vector_cosine_ops`` from ``vec vector_cosine_ops``. Returns ``None`` for plain fields."""
+    match = _VECTOR_OPCLASS_TAIL_RE.search(field_expr)
+    return match.group(1) if match else None
+
+
 def _extract_alias(index_expr: str) -> str | None:
     match = _ALIAS_RE.search(index_expr)
     if match: