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

rebasedming · rebasedming · commit d7abdf32791e · 2026-07-27T11:24:33.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+### Changed
+
+- BM25 index DDL now emits `USING paradedb`, the primary index access method
+  name in pg_search 0.25.0+ (unreleased). Use `HasMethod("bm25")` to keep the
+  backwards-compatible `bm25` alias on released ParadeDB versions.
+
 ## [0.1.2] - 2026-07-14
 
 ## Changed
diff --git a/examples/Shared/ExampleSetup.cs b/examples/Shared/ExampleSetup.cs
@@ -39,25 +39,41 @@ public static string ConnectionString
         }
     }
 
+    // Released ParadeDB versions (<= 0.24.x) only have the `bm25` index access
+    // method; pg_search 0.25.0+ adds `paradedb` as the primary name
+    public static async Task<string> GetIndexAccessMethodAsync(DbContext db)
+    {
+        var hasParadeDbAm = await db
+            .Database.SqlQueryRaw<bool>(
+                """
+                SELECT EXISTS (SELECT 1 FROM pg_am WHERE amname = 'paradedb') AS "Value"
+                """
+            )
+            .SingleAsync();
+
+        return hasParadeDbAm ? "paradedb" : "bm25";
+    }
+
     public static async Task SetupMockItemsAsync(DbContext db)
     {
         await db.Database.ExecuteSqlRawAsync("CREATE EXTENSION IF NOT EXISTS pg_search");
         await db.Database.ExecuteSqlRawAsync(
             "CALL paradedb.create_bm25_test_table(schema_name => 'public', table_name => 'mock_items')"
         );
         await db.Database.ExecuteSqlRawAsync("DROP INDEX IF EXISTS mock_items_bm25_idx");
+        var accessMethod = await GetIndexAccessMethodAsync(db);
         await db.Database.ExecuteSqlRawAsync(
             """
             CREATE INDEX mock_items_bm25_idx ON mock_items
-            USING bm25 (
+            USING paradedb (
                 id,
                 description,
                 rating,
                 (category::pdb.literal('alias=category')),
                 metadata
             )
             WITH (key_field='id', json_fields='{{"metadata":{{"fast":true}}}}');
-            """
+            """.Replace("USING paradedb", $"USING {accessMethod}")
         );
     }
 
@@ -84,17 +100,18 @@ INSERT INTO autocomplete_items (id, description, category, rating, in_stock, cre
             FROM mock_items;
             """
         );
+        var accessMethod = await GetIndexAccessMethodAsync(db);
         await db.Database.ExecuteSqlRawAsync(
             """
             CREATE INDEX autocomplete_items_idx ON autocomplete_items
-            USING bm25 (
+            USING paradedb (
                 id,
                 (description::pdb.unicode_words),
                 (description::pdb.ngram(3,8,'alias=description_ngram')),
                 (category::pdb.literal('alias=category'))
             )
             WITH (key_field='id');
-            """
+            """.Replace("USING paradedb", $"USING {accessMethod}")
         );
     }
 
diff --git a/src/Extensions/ParadeDbIndexBuilderExtensions.cs b/src/Extensions/ParadeDbIndexBuilderExtensions.cs
@@ -131,6 +131,21 @@ public Bm25IndexBuilder<TEntity> IsCreatedConcurrently(bool createdConcurrently
         return this;
     }
 
+    public Bm25IndexBuilder<TEntity> HasMethod(string method)
+    {
+        if (method is not ("paradedb" or "bm25"))
+        {
+            throw new ArgumentException(
+                $"The index access method must be 'paradedb' or 'bm25', but '{method}' was given.",
+                nameof(method)
+            );
+        }
+
+        _indexBuilder.HasAnnotation(ParadeDbAnnotationNames.Bm25IndexMethod, method);
+
+        return this;
+    }
+
     public Bm25IndexBuilder<TEntity> HasSearchTokenizer(Tokenizer tokenizer)
     {
         _indexBuilder.HasAnnotation(
diff --git a/src/Internal/Metadata/ParadeDbAnnotationNames.cs b/src/Internal/Metadata/ParadeDbAnnotationNames.cs
@@ -2,6 +2,7 @@ namespace ParadeDB.EntityFrameworkCore.Internal.Metadata;
 
 internal static class ParadeDbAnnotationNames
 {
+    public const string Bm25IndexMethod = "ParadeDB:Bm25IndexMethod";
     public const string Bm25KeyProperty = "ParadeDB:Bm25KeyProperty";
     public const string Bm25FieldProperties = "ParadeDB:Bm25FieldProperties";
     public const string Bm25FieldKinds = "ParadeDB:Bm25FieldKinds";
diff --git a/src/Internal/Metadata/ParadeDbAnnotationProvider.cs b/src/Internal/Metadata/ParadeDbAnnotationProvider.cs
@@ -84,6 +84,14 @@ is string searchTokenizer
                 searchTokenizer
             );
         }
+
+        if (
+            mappedIndex.FindAnnotation(ParadeDbAnnotationNames.Bm25IndexMethod)?.Value
+            is string indexMethod
+        )
+        {
+            yield return new Annotation(ParadeDbAnnotationNames.Bm25IndexMethod, indexMethod);
+        }
     }
 
     private static string RenderField(
diff --git a/src/Internal/Migrations/ParadeDbMigrationsSqlGenerator.cs b/src/Internal/Migrations/ParadeDbMigrationsSqlGenerator.cs
@@ -40,14 +40,19 @@ is not string keyField
             operation.FindAnnotation(NpgsqlAnnotationNames.CreatedConcurrently)?.Value is true;
         var searchTokenizer =
             operation.FindAnnotation(ParadeDbAnnotationNames.Bm25SearchTokenizer)?.Value as string;
+        var indexMethod =
+            operation.FindAnnotation(ParadeDbAnnotationNames.Bm25IndexMethod)?.Value as string
+            ?? "paradedb";
 
         builder
             .Append("CREATE INDEX ")
             .Append(createdConcurrently ? "CONCURRENTLY " : "")
             .Append(helper.DelimitIdentifier(operation.Name))
             .Append(" ON ")
             .Append(helper.DelimitIdentifier(operation.Table, operation.Schema))
-            .Append(" USING bm25 (")
+            .Append(" USING ")
+            .Append(indexMethod)
+            .Append(" (")
             .Append(string.Join(", ", fields))
             .Append(") WITH (key_field = ")
             .Append(stringMapping.GenerateSqlLiteral(keyField));
diff --git a/tests/IndexingTest.cs b/tests/IndexingTest.cs
@@ -106,11 +106,11 @@ rating int
 
         sql.ShouldBe(
             """
-            CREATE INDEX indexing_items_idx ON indexing_items USING bm25 (id, (description::pdb.ngram(3,3,'positions=true')), ((metadata ->> 'color')::pdb.literal('alias=metadata_color')), (rating::pdb.alias('my_rating_alias')), ((rating + 1)::pdb.alias('escape'' me'))) WITH (key_field = 'id', search_tokenizer = 'simple(lowercase=false)') WHERE rating > 0;
+            CREATE INDEX indexing_items_idx ON indexing_items USING paradedb (id, (description::pdb.ngram(3,3,'positions=true')), ((metadata ->> 'color')::pdb.literal('alias=metadata_color')), (rating::pdb.alias('my_rating_alias')), ((rating + 1)::pdb.alias('escape'' me'))) WITH (key_field = 'id', search_tokenizer = 'simple(lowercase=false)') WHERE rating > 0;
 
             """
         );
-        await context.Database.ExecuteSqlRawAsync(sql);
+        await ExecuteCreateIndexSqlAsync(context, sql);
     }
 
     private sealed class SimpleIndexContext(DbContextOptions<SimpleIndexContext> options)
@@ -155,11 +155,11 @@ rating int
 
         sql.ShouldBe(
             """
-            CREATE INDEX CONCURRENTLY indexing_items_idx ON indexing_items USING bm25 (id, description, metadata) WITH (key_field = 'id');
+            CREATE INDEX CONCURRENTLY indexing_items_idx ON indexing_items USING paradedb (id, description, metadata) WITH (key_field = 'id');
 
             """
         );
-        await context.Database.ExecuteSqlRawAsync(sql);
+        await ExecuteCreateIndexSqlAsync(context, sql);
     }
 
     private sealed class ArrayExpressionIndexContext(
@@ -215,11 +215,11 @@ tags varchar(255)[]
 
         sql.ShouldBe(
             """
-            CREATE INDEX indexing_items_idx ON indexing_items USING bm25 (id, categories, (tags::pdb.literal), ((description || ' ' || category)::pdb.simple('alias=description_concat')), (description::pdb.literal), (description::pdb.simple('alias=description_simple'))) WITH (key_field = 'id');
+            CREATE INDEX indexing_items_idx ON indexing_items USING paradedb (id, categories, (tags::pdb.literal), ((description || ' ' || category)::pdb.simple('alias=description_concat')), (description::pdb.literal), (description::pdb.simple('alias=description_simple'))) WITH (key_field = 'id');
 
             """
         );
-        await context.Database.ExecuteSqlRawAsync(sql);
+        await ExecuteCreateIndexSqlAsync(context, sql);
     }
 
     public static IEnumerable<(
@@ -317,11 +317,140 @@ description text
         var sql = GenerateSearchTokenizerCreateIndexSql(tokenizer);
 
         sql.ShouldBe(
-            $"CREATE INDEX indexing_items_idx ON indexing_items USING bm25 (id, description) WITH (key_field = 'id', search_tokenizer = '{expectedSearchTokenizer}');\n"
+            $"CREATE INDEX indexing_items_idx ON indexing_items USING paradedb (id, description) WITH (key_field = 'id', search_tokenizer = '{expectedSearchTokenizer}');\n"
+        );
+        await ExecuteCreateIndexSqlAsync(context, sql);
+    }
+
+    private sealed class Bm25MethodIndexContext(DbContextOptions<Bm25MethodIndexContext> options)
+        : DbContext(options)
+    {
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<IndexingItem>(entity =>
+            {
+                entity.ToTable("indexing_items");
+                entity.Property(e => e.Id).HasColumnName("id");
+                entity.Property(e => e.Description).HasColumnName("description");
+
+                entity
+                    .HasBm25Index("indexing_items_idx", e => e.Id)
+                    .HasMethod("bm25")
+                    .HasField(e => e.Description);
+            });
+        }
+    }
+
+    [Test]
+    public async Task Bm25Index_WithExplicitBm25Method()
+    {
+        await using var context = DbFixture.CreateContext();
+        await context.Database.OpenConnectionAsync();
+        await context.Database.ExecuteSqlRawAsync(
+            """
+            CREATE TEMP TABLE indexing_items (
+                id int PRIMARY KEY,
+                description text
+            );
+            """
+        );
+
+        var sql = GenerateCreateIndexSql<Bm25MethodIndexContext, IndexingItem>();
+
+        sql.ShouldBe(
+            """
+            CREATE INDEX indexing_items_idx ON indexing_items USING bm25 (id, description) WITH (key_field = 'id');
+
+            """
+        );
+        await context.Database.ExecuteSqlRawAsync(sql);
+    }
+
+    private sealed class ParadeDbMethodIndexContext(
+        DbContextOptions<ParadeDbMethodIndexContext> options
+    ) : DbContext(options)
+    {
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<IndexingItem>(entity =>
+            {
+                entity.ToTable("indexing_items");
+                entity.Property(e => e.Id).HasColumnName("id");
+                entity.Property(e => e.Description).HasColumnName("description");
+
+                entity
+                    .HasBm25Index("indexing_items_idx", e => e.Id)
+                    .HasMethod("paradedb")
+                    .HasField(e => e.Description);
+            });
+        }
+    }
+
+    [Test]
+    public async Task Bm25Index_WithExplicitParadeDbMethod()
+    {
+        var sql = GenerateCreateIndexSql<ParadeDbMethodIndexContext, IndexingItem>();
+
+        sql.ShouldBe(
+            """
+            CREATE INDEX indexing_items_idx ON indexing_items USING paradedb (id, description) WITH (key_field = 'id');
+
+            """
+        );
+
+        Skip.When(
+            !DbFixture.SupportsParadeDbAm,
+            "This ParadeDB version does not have the 'paradedb' index access method (requires pg_search 0.25.0+, unreleased)"
+        );
+
+        await using var context = DbFixture.CreateContext();
+        await context.Database.OpenConnectionAsync();
+        await context.Database.ExecuteSqlRawAsync(
+            """
+            CREATE TEMP TABLE indexing_items (
+                id int PRIMARY KEY,
+                description text
+            );
+            """
         );
         await context.Database.ExecuteSqlRawAsync(sql);
     }
 
+    private sealed class InvalidMethodIndexContext(
+        DbContextOptions<InvalidMethodIndexContext> options
+    ) : DbContext(options)
+    {
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<IndexingItem>(entity =>
+            {
+                entity.ToTable("indexing_items");
+                entity.Property(e => e.Id).HasColumnName("id");
+                entity.Property(e => e.Description).HasColumnName("description");
+
+                entity
+                    .HasBm25Index("indexing_items_idx", e => e.Id)
+                    .HasMethod("gin")
+                    .HasField(e => e.Description);
+            });
+        }
+    }
+
+    [Test]
+    public void Bm25Index_RejectsUnknownMethod()
+    {
+        var exception = Should.Throw<ArgumentException>(() =>
+            GenerateCreateIndexSql<InvalidMethodIndexContext, IndexingItem>()
+        );
+
+        exception.Message.ShouldContain("'paradedb' or 'bm25'");
+    }
+
+    private Task ExecuteCreateIndexSqlAsync(Persistence.TestDbContext context, string sql) =>
+        context.Database.ExecuteSqlRawAsync(
+            sql.Replace(" USING paradedb ", $" USING {DbFixture.AccessMethod} ")
+        );
+
     private static string GenerateCreateIndexSql<TContext, TEntity>()
         where TContext : DbContext
     {
diff --git a/tests/Persistence/DbFixture.cs b/tests/Persistence/DbFixture.cs
@@ -11,6 +11,10 @@ public sealed class DbFixture : IAsyncInitializer, IAsyncDisposable
 
     private DbContextOptions<TestDbContext> _options = null!;
 
+    public string AccessMethod { get; private set; } = "paradedb";
+
+    public bool SupportsParadeDbAm => AccessMethod == "paradedb";
+
     public async Task InitializeAsync()
     {
         _container = new PostgreSqlBuilder("postgres:18")
@@ -28,6 +32,16 @@ public async Task InitializeAsync()
             .Options;
 
         await using var context = new TestDbContext(_options);
+        AccessMethod = await context
+            .Database.SqlQueryRaw<bool>(
+                """
+                SELECT EXISTS (SELECT 1 FROM pg_am WHERE amname = 'paradedb') AS "Value"
+                """
+            )
+            .SingleAsync()
+            ? "paradedb"
+            : "bm25";
+
         await context.Database.ExecuteSqlRawAsync(
             """
             DO $$
@@ -45,7 +59,7 @@ CALL paradedb.create_bm25_test_table(
         await context.Database.ExecuteSqlRawAsync(
             """
             CREATE INDEX IF NOT EXISTS search_idx ON mock_items
-            USING bm25 (
+            USING paradedb (
               id,
               description,
               (description::pdb.simple('alias=description_simple')),
@@ -57,7 +71,7 @@ USING bm25 (
               weight_range
             )
             WITH (key_field='id');
-            """
+            """.Replace("USING paradedb", $"USING {AccessMethod}")
         );
     }
 

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ namespace ParadeDB.EntityFrameworkCore.Internal.Metadata;`
`2`	`2`
`3`	`3`	`internal static class ParadeDbAnnotationNames`
`4`	`4`	`{`
	`5`	`+ public const string Bm25IndexMethod = "ParadeDB:Bm25IndexMethod";`
`5`	`6`	`public const string Bm25KeyProperty = "ParadeDB:Bm25KeyProperty";`
`6`	`7`	`public const string Bm25FieldProperties = "ParadeDB:Bm25FieldProperties";`
`7`	`8`	`public const string Bm25FieldKinds = "ParadeDB:Bm25FieldKinds";`
Original file line number	Diff line number	Diff line change
`@@ -84,6 +84,14 @@ is string searchTokenizer`
`84`	`84`	`searchTokenizer`
`85`	`85`	`);`
`86`	`86`	`}`
	`87`	`+`
	`88`	`+ if (`
	`89`	`+ mappedIndex.FindAnnotation(ParadeDbAnnotationNames.Bm25IndexMethod)?.Value`
	`90`	`+ is string indexMethod`
	`91`	`+ )`
	`92`	`+ {`
	`93`	`+ yield return new Annotation(ParadeDbAnnotationNames.Bm25IndexMethod, indexMethod);`
	`94`	`+ }`
`87`	`95`	`}`
`88`	`96`
`89`	`97`	`private static string RenderField(`