feat!: rename bm25 APIs to paradedb and always use the paradedb 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
 
+### Changed
+
+- **Breaking:** the bm25-named API has been renamed to paradedb, and indexes always use the `paradedb` index access method (requires pg_search 0.25.0+). `BM25Field` is now `ParadeDBField`, `validate_bm25_index` is now `validate_paradedb_index`, the Alembic operations `op.create_bm25_index`/`op.drop_bm25_index`/`op.reindex_bm25` are now `op.create_paradedb_index`/`op.drop_paradedb_index`/`op.reindex_paradedb` (with operation classes `CreateParadeDBIndexOp`/`DropParadeDBIndexOp`/`ReindexParadeDBOp`), and the errors `BM25ValidationError`/`InvalidBM25FieldError` are now `ParadeDBValidationError`/`InvalidParadeDBFieldError`. `Index(postgresql_using="paradedb")` is the only recognized access method; index DDL always emits `USING paradedb`. Existing migrations that call the bm25-named operations must be updated to the paradedb names.
+
 ## [0.8.0] - 2026-07-14
 
 ### Changed

README.md

@@ -36,15 +36,15 @@
 
 ## ParadeDB for SQLAlchemy
 
-The official [SQLAlchemy](https://www.sqlalchemy.org/) integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing BM25 indexes with Alembic and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#sqlalchemy) to begin.
+The official [SQLAlchemy](https://www.sqlalchemy.org/) integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing ParadeDB indexes with Alembic and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#sqlalchemy) to begin.
 
 ## Requirements & Compatibility
 
 | Component  | Supported                     |
 | ---------- | ----------------------------- |
 | Python     | 3.10+                         |
 | SQLAlchemy | 2.0.32+                       |
-| ParadeDB   | 0.22.0+                       |
+| ParadeDB   | 0.25.0+                       |
 | PostgreSQL | 15+ (with ParadeDB extension) |
 
 ## Examples

examples/autocomplete/setup.py

@@ -34,15 +34,15 @@ class Product(Base):
 
 Index(
     "products_autocomplete_bm25_idx",
-    indexing.BM25Field(Product.id),
-    indexing.BM25Field(Product.description),
-    indexing.BM25Field(
+    indexing.ParadeDBField(Product.id),
+    indexing.ParadeDBField(Product.description),
+    indexing.ParadeDBField(
         Product.description,
         tokenizer=tokenizer.ngram(3, 8, options={"prefix_only": True, "alias": "description_ngram"}),
     ),
-    indexing.BM25Field(Product.category, tokenizer=tokenizer.literal()),
-    indexing.BM25Field(Product.rating),
-    postgresql_using="bm25",
+    indexing.ParadeDBField(Product.category, tokenizer=tokenizer.literal()),
+    indexing.ParadeDBField(Product.rating),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

examples/faceted_search/setup.py

@@ -34,11 +34,11 @@ class Product(Base):
 
 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",
+    indexing.ParadeDBField(Product.id),
+    indexing.ParadeDBField(Product.description),
+    indexing.ParadeDBField(Product.category, tokenizer=tokenizer.literal()),
+    indexing.ParadeDBField(Product.rating),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

examples/hybrid_rrf/setup.py

@@ -34,11 +34,11 @@ class Product(Base):
 
 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",
+    indexing.ParadeDBField(Product.id),
+    indexing.ParadeDBField(Product.description),
+    indexing.ParadeDBField(Product.category, tokenizer=tokenizer.literal()),
+    indexing.ParadeDBField(Product.rating),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

examples/more_like_this/setup.py

@@ -34,11 +34,11 @@ class Product(Base):
 
 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",
+    indexing.ParadeDBField(Product.id),
+    indexing.ParadeDBField(Product.description),
+    indexing.ParadeDBField(Product.category, tokenizer=tokenizer.literal()),
+    indexing.ParadeDBField(Product.rating),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

examples/quickstart/setup.py

@@ -34,11 +34,11 @@ class Product(Base):
 
 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",
+    indexing.ParadeDBField(Product.id),
+    indexing.ParadeDBField(Product.description),
+    indexing.ParadeDBField(Product.category, tokenizer=tokenizer.literal()),
+    indexing.ParadeDBField(Product.rating),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

examples/rag/setup.py

@@ -29,9 +29,9 @@ class Document(Base):
 
 Index(
     "documents_bm25_idx",
-    indexing.BM25Field(Document.id),
-    indexing.BM25Field(Document.content),
-    postgresql_using="bm25",
+    indexing.ParadeDBField(Document.id),
+    indexing.ParadeDBField(Document.content),
+    postgresql_using="paradedb",
     postgresql_with={"key_field": "id"},
 )
 

paradedb/__init__.py

@@ -6,7 +6,7 @@
     paradedb_verify_index,
 )
 from .sqlalchemy.facets import with_rows
-from .sqlalchemy.indexing import BM25Field, assert_indexed, describe
+from .sqlalchemy.indexing import ParadeDBField, assert_indexed, describe
 from .sqlalchemy.tokenizer import Tokenizer
 from .sqlalchemy import tokenizer
 from .sqlalchemy.pdb import agg, alias, score, snippet, snippet_positions, snippets
@@ -31,7 +31,7 @@
 )
 
 __all__ = [
-    "BM25Field",
+    "ParadeDBField",
     "ProximityExpr",
     "Tokenizer",
     "agg",