feat: add paradedb-named aliases for bm25-named API (paradedb/paradedb#5706)

Author: rebasedming

CHANGELOG.md

@@ -6,7 +6,8 @@ All notable changes to this project will be documented in this file. The format
 
 ### Added
 
-- Support the `paradedb` index access method (requires pg_search 0.25.0+, unreleased). `ParadeDB::Index` and `add_bm25_index` accept an `am:` option (`"paradedb"` or `"bm25"`), and schema dumps record `am:` when an index does not use the default.
+- Support the `paradedb` index access method (requires pg_search 0.25.0+, unreleased). `ParadeDB::Index` and `add_paradedb_index` accept an `am:` option (`"paradedb"` or `"bm25"`), and schema dumps record `am:` when an index does not use the default.
+- `add_paradedb_index`, `remove_paradedb_index`, and `reindex_paradedb_index` are the primary names for the migration helpers (connection and migration DSL). The `bm25`-named helpers (`add_bm25_index`, `remove_bm25_index`, `reindex_bm25`) remain fully supported aliases. Schema dumps and generated migrations now emit the `paradedb`-named helpers; `schema.rb` files using either name continue to load.
 
 ### Changed
 

examples/autocomplete/setup.rb

@@ -106,7 +106,7 @@ def setup_autocomplete_table!
     puts "  + Copied #{count} products from #{MockItem.table_name}"
 
     puts "\nCreating autocomplete-optimized BM25 index..."
-    conn.remove_bm25_index(:autocomplete_items, name: :autocomplete_items_idx, if_exists: true)
+    conn.remove_paradedb_index(:autocomplete_items, name: :autocomplete_items_idx, if_exists: true)
     ensure_supported_am!(conn, AutocompleteItemIndex)
     conn.create_paradedb_index(AutocompleteItemIndex, if_not_exists: true)
 

examples/faceted_search/setup.rb

@@ -56,7 +56,7 @@ def setup_mock_items!
     )
     conn.execute("DROP TABLE IF EXISTS mock_items_faceted_search CASCADE;")
     conn.execute("CREATE TABLE mock_items_faceted_search AS TABLE mock_items;")
-    conn.remove_bm25_index(:mock_items_faceted_search, name: :mock_items_faceted_search_bm25_idx, if_exists: true)
+    conn.remove_paradedb_index(:mock_items_faceted_search, name: :mock_items_faceted_search_bm25_idx, if_exists: true)
     ensure_supported_am!(conn, MockItemIndex)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 

examples/hybrid_rrf/setup.rb

@@ -64,7 +64,7 @@ def setup_mock_items!
     )
     conn.execute("DROP TABLE IF EXISTS mock_items_hybrid_rrf CASCADE;")
     conn.execute("CREATE TABLE mock_items_hybrid_rrf AS TABLE mock_items;")
-    conn.remove_bm25_index(:mock_items_hybrid_rrf, name: :mock_items_hybrid_rrf_bm25_idx, if_exists: true)
+    conn.remove_paradedb_index(:mock_items_hybrid_rrf, name: :mock_items_hybrid_rrf_bm25_idx, if_exists: true)
     ensure_supported_am!(conn, MockItemIndex)
     conn.create_paradedb_index(MockItemIndex, if_not_exists: true)
 

lib/generators/parade_db/index/templates/migration.rb.tt

@@ -10,6 +10,6 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
   end
 
   def down
-    remove_bm25_index :<%= table_name %>, name: :<%= index_name %>, if_exists: true
+    remove_paradedb_index :<%= table_name %>, name: :<%= index_name %>, if_exists: true
   end
 end

lib/parade_db/migration_helpers.rb

@@ -38,13 +38,15 @@ def add_bm25_index(table, fields:, key_field:, name: nil, index_options: nil, wh
 
       create_paradedb_index(anonymous, if_not_exists: if_not_exists, concurrently: concurrently)
     end
+    alias add_paradedb_index add_bm25_index
 
     def remove_bm25_index(table, name: nil, if_exists: false)
       ensure_postgresql_adapter!
       index_name = (name || "#{table}_bm25_idx").to_s
       prefix = if_exists ? "IF EXISTS " : ""
       execute("DROP INDEX #{prefix}#{quote_table_name(index_name)}")
     end
+    alias remove_paradedb_index remove_bm25_index
 
     def reindex_bm25(table, name: nil, concurrently: false)
       ensure_postgresql_adapter!
@@ -56,6 +58,7 @@ def reindex_bm25(table, name: nil, concurrently: false)
       modifier = concurrently ? " CONCURRENTLY" : ""
       execute("REINDEX INDEX#{modifier} #{quote_table_name(index_name)}")
     end
+    alias reindex_paradedb_index reindex_bm25
 
     def dump_paradedb_indexes(stream)
       rows = paradedb_bm25_index_rows
@@ -343,7 +346,7 @@ def bm25_index_to_ruby(row)
           end
         end
 
-        statement = "add_bm25_index #{table.to_sym.inspect}, " \
+        statement = "add_paradedb_index #{table.to_sym.inspect}, " \
           "fields: { #{fields_pairs.join(', ')} }, " \
           "key_field: #{key_field.to_sym.inspect}, " \
           "name: #{name.inspect}"
@@ -893,6 +896,28 @@ def remove_bm25_index(table, name: nil, if_exists: false)
       def reindex_bm25(table, name: nil, concurrently: false)
         connection.reindex_bm25(table, name: name, concurrently: concurrently)
       end
+
+      def add_paradedb_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, am: nil, if_not_exists: false, concurrently: false)
+        connection.add_paradedb_index(
+          table,
+          fields: fields,
+          key_field: key_field,
+          name: name,
+          index_options: index_options,
+          where: where,
+          am: am,
+          if_not_exists: if_not_exists,
+          concurrently: concurrently
+        )
+      end
+
+      def remove_paradedb_index(table, name: nil, if_exists: false)
+        connection.remove_paradedb_index(table, name: name, if_exists: if_exists)
+      end
+
+      def reindex_paradedb_index(table, name: nil, concurrently: false)
+        connection.reindex_paradedb_index(table, name: name, concurrently: concurrently)
+      end
     end
   end
 
@@ -948,9 +973,12 @@ module CommandRecorderPatch
       %i[
         create_paradedb_index
         add_bm25_index
+        add_paradedb_index
         remove_bm25_index
+        remove_paradedb_index
         replace_paradedb_index
         reindex_bm25
+        reindex_paradedb_index
       ].each do |method_name|
         define_method(method_name) do |*args, &block|
           record(method_name, args, &block)
@@ -965,7 +993,7 @@ def invert_create_paradedb_index(args)
         compiled = resolve_paradedb_index_klass(index_klass).compiled_definition
         remove_options = Hash.ruby2_keywords_hash(name: compiled.index_name, if_exists: true)
 
-        [:remove_bm25_index, [compiled.table_name, remove_options]]
+        [:remove_paradedb_index, [compiled.table_name, remove_options]]
       end
 
       def invert_add_bm25_index(args)
@@ -976,14 +1004,20 @@ def invert_add_bm25_index(args)
         remove_options[:name] = options[:name] if options[:name]
         remove_options = Hash.ruby2_keywords_hash(remove_options)
 
-        [:remove_bm25_index, [table, remove_options]]
+        [:remove_paradedb_index, [table, remove_options]]
       end
+      alias_method :invert_add_paradedb_index, :invert_add_bm25_index
 
       def invert_remove_bm25_index(_args)
         raise ActiveRecord::IrreversibleMigration,
               "remove_bm25_index is not automatically reversible. Use #up/#down or #reversible."
       end
 
+      def invert_remove_paradedb_index(_args)
+        raise ActiveRecord::IrreversibleMigration,
+              "remove_paradedb_index is not automatically reversible. Use #up/#down or #reversible."
+      end
+
       def invert_replace_paradedb_index(_args)
         raise ActiveRecord::IrreversibleMigration,
               "replace_paradedb_index is not automatically reversible. Use #up/#down or #reversible."
@@ -994,6 +1028,11 @@ def invert_reindex_bm25(_args)
               "reindex_bm25 is not automatically reversible. Use #up/#down or #reversible."
       end
 
+      def invert_reindex_paradedb_index(_args)
+        raise ActiveRecord::IrreversibleMigration,
+              "reindex_paradedb_index is not automatically reversible. Use #up/#down or #reversible."
+      end
+
       def resolve_paradedb_index_klass(index_klass)
         case index_klass
         when String

spec/index_dsl_unit_spec.rb

@@ -299,7 +299,7 @@
     recorder = Class.new do
       attr_reader :captured
 
-      def add_bm25_index(table, fields:, key_field:, name:, index_options: nil, if_not_exists: false)
+      def add_paradedb_index(table, fields:, key_field:, name:, index_options: nil, if_not_exists: false)
         @captured = {
           table: table,
           fields: fields,
@@ -346,7 +346,7 @@ def add_bm25_index(table, fields:, key_field:, name:, index_options: nil, if_not
     )
 
     assert_equal(
-      %(add_bm25_index :products, fields: { id: {}, description: {} }, key_field: :id, name: "products_bm25_idx", am: "bm25"),
+      %(add_paradedb_index :products, fields: { id: {}, description: {} }, key_field: :id, name: "products_bm25_idx", am: "bm25"),
       ruby_stmt
     )
   end
@@ -370,7 +370,7 @@ def add_bm25_index(table, fields:, key_field:, name:, index_options: nil, if_not
     )
 
     assert_equal(
-      %(add_bm25_index :products, fields: { id: {}, description: {} }, key_field: :id, name: "products_bm25_idx"),
+      %(add_paradedb_index :products, fields: { id: {}, description: {} }, key_field: :id, name: "products_bm25_idx"),
       ruby_stmt
     )
   end
@@ -389,4 +389,37 @@ def add_bm25_index(table, fields:, key_field:, name:, index_options: nil, if_not
     assert_equal "key_field=id, target_segment_count=((17))", with_sql
     assert_equal "WHERE ((archived_at IS NULL))", trailing_sql
   end
+
+  it "exposes paradedb-named aliases for the bm25 migration helpers" do
+    conn = ActiveRecord::Base.connection
+
+    {
+      add_paradedb_index: :add_bm25_index,
+      remove_paradedb_index: :remove_bm25_index,
+      reindex_paradedb_index: :reindex_bm25
+    }.each do |alias_name, original|
+      assert conn.respond_to?(alias_name)
+      assert conn.respond_to?(original)
+      assert_equal conn.method(original).parameters, conn.method(alias_name).parameters
+      assert ParadeDB::MigrationDSL.method_defined?(alias_name)
+      assert ParadeDB::MigrationDSL.method_defined?(original)
+    end
+  end
+
+  it "inverts index helpers to paradedb-named commands in the command recorder" do
+    recorder = ActiveRecord::Migration::CommandRecorder.new(ActiveRecord::Base.connection)
+
+    %i[add_paradedb_index add_bm25_index].each do |command|
+      method, args = recorder.inverse_of(command, [:products, { key_field: :id, name: :products_alias_idx }])
+      assert_equal :remove_paradedb_index, method
+      assert_equal :products, args.first
+      assert_equal({ if_exists: true, name: :products_alias_idx }, args.last)
+    end
+
+    %i[remove_paradedb_index reindex_paradedb_index remove_bm25_index reindex_bm25].each do |command|
+      assert_raises(ActiveRecord::IrreversibleMigration) do
+        recorder.inverse_of(command, [:products])
+      end
+    end
+  end
 end

spec/index_generator_unit_spec.rb

@@ -90,10 +90,10 @@ def generated_migration_path(model)
       expect(content).to include("create_paradedb_index(ProductIndex, if_not_exists: true)")
     end
 
-    it "calls remove_bm25_index in down" do
+    it "calls remove_paradedb_index in down" do
       run_generator(["Product"])
       content = File.read(generated_migration_path("Product"))
-      expect(content).to include("remove_bm25_index :products, name: :products_bm25_idx, if_exists: true")
+      expect(content).to include("remove_paradedb_index :products, name: :products_bm25_idx, if_exists: true")
     end
 
     it "does not include disable_ddl_transaction! by default" do
@@ -126,7 +126,7 @@ def generated_migration_path(model)
       run_generator(["LineItem"])
       content = File.read(generated_migration_path("LineItem"))
       expect(content).to include("class CreateLineItemBm25Index")
-      expect(content).to include("remove_bm25_index :line_items")
+      expect(content).to include("remove_paradedb_index :line_items")
     end
   end
 end

spec/index_migration_integration_spec.rb

@@ -274,6 +274,71 @@ class IndexMigrationBookByNameIndex < ParadeDB::Index
     assert_not index_exists?("books_custom_bm25_idx")
   end
 
+  it "supports the paradedb-named alias helpers end-to-end" do
+    conn = ActiveRecord::Base.connection
+    conn.remove_paradedb_index(:books, if_exists: true)
+    conn.remove_paradedb_index(:books, name: :books_alias_idx, if_exists: true)
+
+    conn.add_paradedb_index(
+      :books,
+      fields: {
+        id: {},
+        title: { tokenizer: ParadeDB::Tokenizer.simple() }
+      },
+      key_field: :id,
+      name: :books_alias_idx,
+      am: paradedb_test_am
+    )
+    assert index_exists?("books_alias_idx")
+
+    conn.reindex_paradedb_index(:books, name: :books_alias_idx)
+
+    conn.remove_paradedb_index(:books, name: :books_alias_idx)
+    assert_not index_exists?("books_alias_idx")
+  end
+
+  it "rolls back add_paradedb_index in change migrations" do
+    conn = ActiveRecord::Base.connection
+    conn.remove_paradedb_index(:books, if_exists: true)
+    conn.remove_paradedb_index(:books, name: :books_alias_idx, if_exists: true)
+
+    migration = build_change_migration do
+      add_paradedb_index(
+        :books,
+        fields: {
+          id: {},
+          title: { tokenizer: ParadeDB::Tokenizer.simple() }
+        },
+        key_field: :id,
+        name: :books_alias_idx,
+        am: paradedb_test_am,
+        if_not_exists: true
+      )
+    end
+
+    run_migration(migration, :up, connection: conn)
+    assert index_exists?("books_alias_idx")
+
+    run_migration(migration, :down, connection: conn)
+    assert_not index_exists?("books_alias_idx")
+  end
+
+  it "raises for remove_paradedb_index in change migrations" do
+    conn = ActiveRecord::Base.connection
+
+    migration = build_change_migration do
+      remove_paradedb_index(:books, if_exists: true)
+    end
+
+    run_migration(migration, :up, connection: conn)
+    assert_not index_exists?("books_bm25_idx")
+
+    error = assert_raises(ActiveRecord::IrreversibleMigration) do
+      run_migration(migration, :down, connection: conn)
+    end
+    assert_includes error.message, "remove_paradedb_index"
+  end
+
   it "raises for remove_bm25_index in change migrations" do
     conn = ActiveRecord::Base.connection
 
@@ -399,13 +464,13 @@ class IndexMigrationBookByNameIndex < ParadeDB::Index
     schema = stream.string
 
     add_stmt = schema.each_line.find do |line|
-      line.include?("add_bm25_index :books") &&
+      line.include?("add_paradedb_index :books") &&
         line.include?("title_simple") &&
         line.include?("target_segment_count")
     end
 
     assert_equal <<~RUBY.strip, add_stmt.to_s.strip
-      add_bm25_index :books, fields: { id: {}, title: { tokenizer: ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" }) } }, key_field: :id, name: "books_bm25_idx", index_options: { :target_segment_count => 17 }#{paradedb_test_am_dump_suffix}
+      add_paradedb_index :books, fields: { id: {}, title: { tokenizer: ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" }) } }, key_field: :id, name: "books_bm25_idx", index_options: { :target_segment_count => 17 }#{paradedb_test_am_dump_suffix}
     RUBY
     expect(schema).not_to match(/add_index.*books_bm25_idx/)
     expect(schema).not_to match(/t\.index.*books_bm25_idx/)
@@ -497,13 +562,13 @@ class IndexMigrationBookByNameIndex < ParadeDB::Index
     ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, stream)
     schema = stream.string
     add_stmt = schema.each_line.find do |line|
-      line.include?("add_bm25_index :books") &&
+      line.include?("add_paradedb_index :books") &&
         line.include?("title_simple") &&
         line.include?("target_segment_count")
     end
 
     assert_equal <<~RUBY.strip, add_stmt.to_s.strip
-      add_bm25_index :books, fields: { id: {}, title: { tokenizers: [ParadeDB::Tokenizer.literal(), ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" })] } }, key_field: :id, name: "books_bm25_idx", index_options: { :target_segment_count => 17 }#{paradedb_test_am_dump_suffix}
+      add_paradedb_index :books, fields: { id: {}, title: { tokenizers: [ParadeDB::Tokenizer.literal(), ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" })] } }, key_field: :id, name: "books_bm25_idx", index_options: { :target_segment_count => 17 }#{paradedb_test_am_dump_suffix}
     RUBY
 
     conn.remove_bm25_index(:books, if_exists: true)
@@ -532,11 +597,11 @@ class IndexMigrationBookByNameIndex < ParadeDB::Index
     ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, stream)
     schema = stream.string
     add_stmt = schema.each_line.find do |line|
-      line.include?("add_bm25_index :books") && line.include?("metadata_title_text")
+      line.include?("add_paradedb_index :books") && line.include?("metadata_title_text")
     end
 
     assert_equal <<~RUBY.strip, add_stmt.to_s.strip
-      add_bm25_index :books, fields: { id: {}, "metadata ->> 'title'::text" => { tokenizer: ParadeDB::Tokenizer.simple(options: { :lowercase => true, :alias => "metadata_title_text" }) } }, key_field: :id, name: "books_bm25_idx"#{paradedb_test_am_dump_suffix}
+      add_paradedb_index :books, fields: { id: {}, "metadata ->> 'title'::text" => { tokenizer: ParadeDB::Tokenizer.simple(options: { :lowercase => true, :alias => "metadata_title_text" }) } }, key_field: :id, name: "books_bm25_idx"#{paradedb_test_am_dump_suffix}
     RUBY
 
     conn.remove_bm25_index(:books, if_exists: true)
@@ -564,13 +629,13 @@ class IndexMigrationBookByNameIndex < ParadeDB::Index
     ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, stream)
     schema = stream.string
     add_stmt = schema.each_line.find do |line|
-      line.include?("add_bm25_index :books") &&
+      line.include?("add_paradedb_index :books") &&
         line.include?("title_simple") &&
         line.include?("where:")
     end
 
     assert_equal <<~RUBY.strip, add_stmt.to_s.strip
-      add_bm25_index :books, fields: { id: {}, title: { tokenizer: ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" }) } }, key_field: :id, name: "books_bm25_idx", where: "author IS NOT NULL"#{paradedb_test_am_dump_suffix}
+      add_paradedb_index :books, fields: { id: {}, title: { tokenizer: ParadeDB::Tokenizer.simple(options: { :alias => "title_simple" }) } }, key_field: :id, name: "books_bm25_idx", where: "author IS NOT NULL"#{paradedb_test_am_dump_suffix}
     RUBY
 
     conn.remove_bm25_index(:books, if_exists: true)