feat: support the paradedb index access method (paradedb/paradedb#5706)

Author: rebasedming

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format
 
 ## Unreleased
 
+### Added
+
+- Support for the `paradedb` index access method, the primary name on pg_search 0.25.0+ (`bm25` remains a permanent alias). `op.create_bm25_index` and `op.drop_bm25_index` emit `USING paradedb` by default and accept an `am` option (`"paradedb"` or `"bm25"`); `Index(postgresql_using=...)`, validation, introspection, and Alembic autogenerate recognize ParadeDB indexes under either name without producing migration churn. New `indexing.server_index_access_method(engine)` helper probes which name the server supports.
+
 ## [0.8.0] - 2026-07-14
 
 ### Changed

examples/autocomplete/setup.py

@@ -32,7 +32,7 @@ class Product(Base):
     rating: Mapped[int] = mapped_column(Integer, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "products_autocomplete_bm25_idx",
     indexing.BM25Field(Product.id),
     indexing.BM25Field(Product.description),
@@ -42,7 +42,7 @@ class Product(Base):
     ),
     indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
     indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -53,6 +53,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

examples/faceted_search/setup.py

@@ -32,13 +32,13 @@ class Product(Base):
     rating: Mapped[int] = mapped_column(Integer, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "products_facets_bm25_idx",
     indexing.BM25Field(Product.id),
     indexing.BM25Field(Product.description),
     indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
     indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -49,6 +49,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

examples/hybrid_rrf/setup.py

@@ -32,13 +32,13 @@ class Product(Base):
     rating: Mapped[int] = mapped_column(Integer, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "products_hybrid_rrf_bm25_idx",
     indexing.BM25Field(Product.id),
     indexing.BM25Field(Product.description),
     indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
     indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -49,6 +49,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

examples/more_like_this/setup.py

@@ -32,13 +32,13 @@ class Product(Base):
     rating: Mapped[int] = mapped_column(Integer, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "products_mlt_bm25_idx",
     indexing.BM25Field(Product.id),
     indexing.BM25Field(Product.description),
     indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
     indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -49,6 +49,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

examples/quickstart/setup.py

@@ -32,13 +32,13 @@ class Product(Base):
     rating: Mapped[int] = mapped_column(Integer, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "products_bm25_idx",
     indexing.BM25Field(Product.id),
     indexing.BM25Field(Product.description),
     indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
     indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -49,6 +49,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

examples/rag/setup.py

@@ -27,11 +27,11 @@ class Document(Base):
     content: Mapped[str] = mapped_column(Text, nullable=False)
 
 
-Index(
+SEARCH_INDEX = Index(
     "documents_bm25_idx",
     indexing.BM25Field(Document.id),
     indexing.BM25Field(Document.content),
-    postgresql_using="bm25",
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 
@@ -42,6 +42,8 @@ def engine_from_env() -> Engine:
 
 
 def setup_database(engine: Engine) -> None:
+    # pg_search <= 0.24.x only exposes the backwards-compatible bm25 alias.
+    SEARCH_INDEX.dialect_options["postgresql"]["using"] = indexing.server_index_access_method(engine)
     Base.metadata.drop_all(engine)
     Base.metadata.create_all(engine)
     with Session(engine) as session:

paradedb/sqlalchemy/alembic.py

@@ -9,6 +9,8 @@
 from sqlalchemy.dialects import postgresql
 from sqlalchemy.sql.elements import ClauseElement
 
+from .indexing import DEFAULT_INDEX_ACCESS_METHOD, validate_index_access_method
+
 
 def _quote_ident(name: str) -> str:
     return '"' + name.replace('"', '""') + '"'
@@ -35,13 +37,15 @@ def __init__(
         *,
         table_schema: str | None = None,
         where: str | None = None,
+        am: str = DEFAULT_INDEX_ACCESS_METHOD,
     ) -> None:
         self.index_name = index_name
         self.table_name = table_name
         self.expressions = expressions
         self.key_field = key_field
         self.table_schema = table_schema
         self.where = where
+        self.am = validate_index_access_method(am)
 
     @classmethod
     def create_bm25_index(
@@ -54,6 +58,7 @@ def create_bm25_index(
         key_field: str,
         table_schema: str | None = None,
         where: str | None = None,
+        am: str = DEFAULT_INDEX_ACCESS_METHOD,
     ) -> MigrateOperation:
         return operations.invoke(
             cls(
@@ -63,11 +68,12 @@ def create_bm25_index(
                 key_field,
                 table_schema=table_schema,
                 where=where,
+                am=am,
             )
         )
 
     def reverse(self) -> MigrateOperation:
-        return DropBM25IndexOp(index_name=self.index_name, if_exists=True, schema=self.table_schema)
+        return DropBM25IndexOp(index_name=self.index_name, if_exists=True, schema=self.table_schema, am=self.am)
 
 
 @Operations.implementation_for(CreateBM25IndexOp)
@@ -76,7 +82,7 @@ def _create_bm25_index_impl(operations: Operations, operation: CreateBM25IndexOp
     sql = (
         f"CREATE INDEX {_quote_ident(operation.index_name)} "
         f"ON {_quote_qualified(operation.table_schema, operation.table_name)} "
-        f"USING bm25 ({expressions_sql}) WITH (key_field={_quote_literal(operation.key_field)})"
+        f"USING {operation.am} ({expressions_sql}) WITH (key_field={_quote_literal(operation.key_field)})"
     )
     if operation.where is not None:
         sql += f" WHERE {operation.where}"
@@ -95,6 +101,8 @@ def _render_create_bm25_index_op(autogen_context, op: CreateBM25IndexOp) -> str:
         parts.append(f"table_schema={op.table_schema!r}")
     if op.where is not None:
         parts.append(f"where={op.where!r}")
+    if op.am != DEFAULT_INDEX_ACCESS_METHOD:
+        parts.append(f"am={op.am!r}")
     return f"op.create_bm25_index({', '.join(parts)})"
 
 
@@ -110,6 +118,7 @@ def __init__(
         expressions: list[str] | None = None,
         key_field: str | None = None,
         where: str | None = None,
+        am: str = DEFAULT_INDEX_ACCESS_METHOD,
     ) -> None:
         self.index_name = index_name
         self.if_exists = if_exists
@@ -118,6 +127,7 @@ def __init__(
         self.expressions = expressions
         self.key_field = key_field
         self.where = where
+        self.am = validate_index_access_method(am)
 
     @classmethod
     def drop_bm25_index(
@@ -131,6 +141,7 @@ def drop_bm25_index(
         expressions: list[str] | None = None,
         key_field: str | None = None,
         where: str | None = None,
+        am: str = DEFAULT_INDEX_ACCESS_METHOD,
     ) -> MigrateOperation:
         return operations.invoke(
             cls(
@@ -141,6 +152,7 @@ def drop_bm25_index(
                 expressions=expressions,
                 key_field=key_field,
                 where=where,
+                am=am,
             )
         )
 
@@ -155,6 +167,7 @@ def reverse(self) -> MigrateOperation:
             key_field=self.key_field,
             table_schema=self.schema,
             where=self.where,
+            am=self.am,
         )
 
 
@@ -177,6 +190,8 @@ def _render_drop_bm25_index_op(autogen_context, op: DropBM25IndexOp) -> str:
         parts.append(f"key_field={op.key_field!r}")
     if op.where is not None:
         parts.append(f"where={op.where!r}")
+    if op.am != DEFAULT_INDEX_ACCESS_METHOD:
+        parts.append(f"am={op.am!r}")
     return f"op.drop_bm25_index({', '.join(parts)})"
 
 
@@ -229,7 +244,7 @@ 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."""
+    """Return {(schema, index_name): {table_name, expressions, key_field, where, am}} from pg_indexes."""
     from .indexing import (
         _extract_key_field,
         _extract_where_clause,
@@ -249,6 +264,7 @@ def _autogen_bm25_db_indexes(conn, effective_schemas: set[str]) -> dict[tuple[st
                     "expressions": [],
                     "key_field": _normalize_reloption_value(row["key_field"]) or "",
                     "where": _extract_where_clause(str(row["indexdef"])),
+                    "am": str(row["amname"]),
                 },
             )
             index_entry["expressions"].append(str(row["keydef"]))
@@ -447,6 +463,7 @@ def _compare_bm25_indexes(autogen_context, upgrade_ops, schemas) -> PriorityDisp
                     expressions=db["expressions"],
                     key_field=db["key_field"],
                     where=db.get("where"),
+                    am=db["am"],
                 )
             )
 
@@ -467,11 +484,15 @@ def _compare_bm25_indexes(autogen_context, upgrade_ops, schemas) -> PriorityDisp
             key_field=key_field,
             table_schema=key[0],
             where=meta_where,
+            am=validate_index_access_method(index.dialect_options["postgresql"].get("using")),
         )
 
         if key not in db_bm25:
             upgrade_ops.ops.append(create_op)
         else:
+            # The AM name is intentionally not compared: paradedb and bm25 are
+            # aliases for the same access method, so an AM-only difference must
+            # not produce migration churn.
             db = db_bm25[key]
             expressions_changed = _normalized_expression_list(db["expressions"]) != _normalized_expression_list(
                 expressions
@@ -488,6 +509,7 @@ def _compare_bm25_indexes(autogen_context, upgrade_ops, schemas) -> PriorityDisp
                         expressions=db["expressions"],
                         key_field=db["key_field"],
                         where=db.get("where"),
+                        am=db["am"],
                     )
                 )
                 upgrade_ops.ops.append(create_op)

paradedb/sqlalchemy/indexing.py

@@ -58,9 +58,33 @@ def _compile_bm25_field_default(element: BM25Field, compiler, **kw: Any) -> str:
     raise CompileError("BM25Field is only supported for PostgreSQL dialects")
 
 
+DEFAULT_INDEX_ACCESS_METHOD = "paradedb"
+INDEX_ACCESS_METHODS = ("paradedb", "bm25")
+
+
+def validate_index_access_method(am: str) -> str:
+    """Normalize *am* and raise :exc:`InvalidArgumentError` unless it is a ParadeDB access method."""
+    normalized = str(am).lower()
+    if normalized not in INDEX_ACCESS_METHODS:
+        raise InvalidArgumentError(f"index access method must be one of: {', '.join(INDEX_ACCESS_METHODS)}")
+    return normalized
+
+
+def server_index_access_method(bind: Engine | Any) -> str:
+    """Return ``"paradedb"`` when the server exposes the ``paradedb`` index access method
+    (pg_search 0.25.0+), otherwise the backwards-compatible ``"bm25"`` alias."""
+    query = text("SELECT 1 FROM pg_am WHERE amname = 'paradedb'")
+    if isinstance(bind, Engine):
+        with bind.connect() as conn:
+            row = conn.execute(query).first()
+    else:
+        row = bind.execute(query).first()
+    return "paradedb" if row is not None else "bm25"
+
+
 def _is_bm25_index(index: Index) -> bool:
     using = index.dialect_options["postgresql"].get("using")
-    return bool(using and str(using).lower() == "bm25")
+    return bool(using) and str(using).lower() in INDEX_ACCESS_METHODS
 
 
 def _bm25_field_name(field: BM25Field) -> str | None:
@@ -169,7 +193,7 @@ def _split_top_level_csv(expr: str) -> list[str]:
 
 
 def _extract_bm25_field_list(indexdef: str) -> list[str]:
-    marker = re.search(r"USING\s+bm25\s*\(", indexdef, re.IGNORECASE)
+    marker = re.search(r"USING\s+(?:bm25|paradedb)\s*\(", indexdef, re.IGNORECASE)
     if marker is None:
         return []
 
@@ -308,6 +332,7 @@ def _introspect_bm25_index_rows(conn, *, schema_name: str, table_name: str | Non
               ns.nspname AS schemaname,
               tbl.relname AS tablename,
               idx.relname AS indexname,
+              am.amname AS amname,
               pg_get_indexdef(idx.oid) AS indexdef,
               split_part(opt.opt, '=', 2) AS key_field,
               key_ord.ord::int AS ordinality,
@@ -317,6 +342,7 @@ def _introspect_bm25_index_rows(conn, *, schema_name: str, table_name: str | Non
             JOIN pg_namespace AS ns ON ns.oid = idx.relnamespace
             JOIN pg_index AS i ON i.indexrelid = idx.oid
             JOIN pg_class AS tbl ON tbl.oid = i.indrelid
+            JOIN pg_am AS am ON am.oid = idx.relam
             LEFT JOIN LATERAL (
               SELECT opt
               FROM unnest(COALESCE(idx.reloptions, ARRAY[]::text[])) AS opt
@@ -329,7 +355,7 @@ def _introspect_bm25_index_rows(conn, *, schema_name: str, table_name: str | Non
              AND attr.attnum = key_ord.attnum
             WHERE ns.nspname = :schema_name
               AND (CAST(:table_name AS text) IS NULL OR tbl.relname = CAST(:table_name AS text))
-              AND pg_get_indexdef(idx.oid) ILIKE '%USING bm25%'
+              AND am.amname IN ('bm25', 'paradedb')
             ORDER BY idx.relname, key_ord.ord
             """
             ),