feat!: rename bm25 APIs to paradedb and always use the paradedb access method (paradedb/paradedb#5706)

Author: rebasedming

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to this project will be documented in this file. The format
 
 ## Unreleased
 
+### Changed
+
+- **Breaking**: `BM25Index` is renamed to `ParadeDBIndex`, and indexes are always created with `USING paradedb`. This release requires pg_search 0.25.0+. Update model definitions and existing migrations to the new class name.
+
 ## [0.10.0] - 2026-07-14
 
 ### Removed

README.md

@@ -36,7 +36,7 @@
 
 ## ParadeDB for Django
 
-The official [Django](https://www.djangoproject.com/) 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 and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#django) to begin.
+The official [Django](https://www.djangoproject.com/) 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 and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#django) to begin.
 
 ## Requirements & Compatibility
 

examples/README.md

@@ -49,7 +49,7 @@ _The "Hello World" of ParadeDB._
 
 This script demonstrates the fundamental building blocks of search. You will learn how to:
 
-- **Index data**: Define a `BM25Index` on your model.
+- **Index data**: Define a `ParadeDBIndex` on your model.
 - **Search**: Perform basic keyword queries.
 - **Score**: Sort results by relevance (BM25 score).
 - **Highlight**: Generate snippets (e.g., `<b>run</b>ning`) to show users why a result matched.

examples/autocomplete/models.py

@@ -3,7 +3,7 @@
 from common import configure_django
 from django.db import models
 
-from paradedb.indexes import BM25Index
+from paradedb.indexes import ParadeDBIndex
 from paradedb.queryset import ParadeDBManager
 from paradedb.search import Tokenizer
 
@@ -25,7 +25,7 @@ class Meta:
         managed = False
         db_table = "autocomplete_items"
         indexes = (
-            BM25Index(
+            ParadeDBIndex(
                 fields={
                     "id": {},
                     "description": {

examples/autocomplete/setup.py

@@ -17,7 +17,7 @@ def setup_autocomplete_table() -> int:
     from django.db import connection
 
     with connection.cursor() as cursor:
-        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search")
+        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE")
 
         # Ensure mock_items exists first
         cursor.execute(

examples/common.py

@@ -10,7 +10,7 @@
 import django
 from django.conf import settings
 
-from paradedb.indexes import BM25Index
+from paradedb.indexes import ParadeDBIndex
 from paradedb.queryset import ParadeDBManager
 from paradedb.search import Tokenizer
 
@@ -64,7 +64,7 @@ def setup_mock_items() -> int:
     from django.db import connection
 
     with connection.cursor() as cursor:
-        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search")
+        cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE")
         cursor.execute(
             "CALL paradedb.create_bm25_test_table("
             "schema_name => 'public', table_name => 'mock_items')"
@@ -88,9 +88,9 @@ def setup_mock_items() -> int:
 from django.db import models  # noqa: E402
 
 
-def _mock_items_indexes() -> list[BM25Index]:
+def _mock_items_indexes() -> list[ParadeDBIndex]:
     return [
-        BM25Index(
+        ParadeDBIndex(
             fields={
                 "id": {},
                 "description": {},

paradedb/__init__.py

@@ -14,7 +14,6 @@
 __all__ = [
     "Agg",
     "All",
-    "BM25Index",
     "Boost",
     "Const",
     "Exists",
@@ -25,6 +24,7 @@
     "MatchAny",
     "MoreLikeThis",
     "ParadeDB",
+    "ParadeDBIndex",
     "ParadeDBManager",
     "ParadeDBQuerySet",
     "Parse",
@@ -65,8 +65,8 @@
         "paradedb_verify_all_indexes",
     ),
     "paradedb_verify_index": ("paradedb.functions", "paradedb_verify_index"),
-    "BM25Index": ("paradedb.indexes", "BM25Index"),
     "IndexExpression": ("paradedb.indexes", "IndexExpression"),
+    "ParadeDBIndex": ("paradedb.indexes", "ParadeDBIndex"),
     "ParadeDBManager": ("paradedb.queryset", "ParadeDBManager"),
     "ParadeDBQuerySet": ("paradedb.queryset", "ParadeDBQuerySet"),
     "All": ("paradedb.search", "All"),

paradedb/indexes.py

@@ -1,4 +1,4 @@
-"""BM25 index support for Django models."""
+"""ParadeDB (BM25) index support for Django models."""
 
 from __future__ import annotations
 
@@ -138,9 +138,9 @@ class IndexExpression:
 
         from django.db.models import F
         from django.db.models.functions import Lower
-        from paradedb.indexes import BM25Index, IndexExpression
+        from paradedb.indexes import ParadeDBIndex, IndexExpression
 
-        BM25Index(
+        ParadeDBIndex(
             fields={"id": {}, "description": {}},
             expressions=[
                 # Text expression with tokenizer
@@ -165,8 +165,12 @@ class IndexExpression:
     tokenizer: Tokenizer | None = None
 
 
-class BM25Index(models.Index):
-    """BM25 index for ParadeDB."""
+class ParadeDBIndex(models.Index):
+    """ParadeDB search (BM25) index.
+
+    The index is created with ``USING paradedb``, the index access method
+    name in pg_search 0.25.0+.
+    """
 
     suffix = "bm25"
 
@@ -218,7 +222,7 @@ def create_sql(
             create_stmt += " CONCURRENTLY"
         template = (
             f"{create_stmt} %(name)s ON %(table)s\n"
-            "USING bm25 (\n"
+            "USING paradedb (\n"
             "    %(expressions)s\n"
             ")\n"
             f"WITH ({', '.join(storage_params)})"
@@ -381,4 +385,4 @@ def _build_json_key_expressions(
         return expressions
 
 
-__all__ = ["BM25Index", "IndexExpression"]
+__all__ = ["IndexExpression", "ParadeDBIndex"]

tests/conftest.py

@@ -66,7 +66,7 @@ def paradedb_ready(django_db_setup: object, django_db_blocker: object) -> None:
 
     with django_db_blocker.unblock(), connection.cursor() as cursor:
         try:
-            cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search;")
+            cursor.execute("CREATE EXTENSION IF NOT EXISTS pg_search CASCADE;")
         except Exception as exc:  # pragma: no cover - defensive skip
             pytest.fail(
                 f"ParadeDB pg_search extension unavailable in target database: {exc}"
@@ -76,7 +76,7 @@ def paradedb_ready(django_db_setup: object, django_db_blocker: object) -> None:
         )
         cursor.execute("DROP INDEX IF EXISTS mock_items_bm25_idx;")
         cursor.execute(
-            "CREATE INDEX mock_items_bm25_idx ON mock_items USING bm25 ("
+            "CREATE INDEX mock_items_bm25_idx ON mock_items USING paradedb ("
             "id, "
             "description, "
             "category, "

tests/test_error_handling.py

@@ -99,7 +99,7 @@ def test_notices_do_not_raise_exceptions(self) -> None:
         with connection.cursor() as cursor:
             cursor.execute(
                 "CREATE INDEX IF NOT EXISTS mock_items_bm25_idx ON mock_items "
-                "USING bm25 (id, description) WITH (key_field='id');"
+                "USING paradedb (id, description) WITH (key_field='id');"
             )
             cursor.execute("SELECT COUNT(*) FROM mock_items;")
             (count,) = cursor.fetchone()