fix: address review feedback

Author: rebasedming

README.md

@@ -36,7 +36,7 @@
 
 ## ParadeDB for Rails
 
-The official ActiveRecord 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#rails) to begin.
+The official ActiveRecord 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. The integration covers both full-text (BM25) and vector search — vector search indexes pgvector `vector(n)` columns directly. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
 
 ## Requirements & Compatibility
 
@@ -46,17 +46,18 @@ The official ActiveRecord integration for [ParadeDB](https://paradedb.com) (powe
 | Rails      | 7.2+                                             |
 | ParadeDB   | 0.22.0+                                          |
 | PostgreSQL | 15+ (PostgreSQL adapter with ParadeDB extension) |
+| pgvector   | Required for vector search (ships with ParadeDB) |
 
 ## Vector Search
 
-rails-paradedb natively supports pgvector `vector(n)` columns — no `neighbor` or other pgvector gem required. Declare the column, list it in the BM25 index with a distance metric, and run Top-K queries:
+rails-paradedb natively supports pgvector `vector(n)` columns — no `neighbor` or other pgvector gem required. Declare the column, list it in the ParadeDB index with a distance metric, and run Top-K queries:
 
 ```ruby
 class AddVectorSearchToProducts < ActiveRecord::Migration[8.1]
   def change
     add_column :products, :embedding, :vector, limit: 384
 
-    add_bm25_index :products,
+    add_paradedb_index :products,
                    fields: { id: {}, description: {}, embedding: { metric: :l2 } },
                    key_field: :id
   end
@@ -73,7 +74,7 @@ Product.nearest(:embedding, query_embedding).limit(10)
 Product.search(:description).match_all("shoes").nearest(:embedding, query_embedding).limit(10)
 ```
 
-Top-K index pushdown requires a `LIMIT`, and the query metric must match the index opclass metric — a mismatch still returns correct results but silently falls back to a plain sort. Vector columns inside BM25 indexes require a ParadeDB build with bm25 vector opclasses (not yet in a released ParadeDB version); the plain `vector(n)` column type and distance expressions work on any ParadeDB or Postgres with pgvector.
+Top-K index pushdown requires a `LIMIT`, and the query metric must match the index opclass metric — a mismatch still returns correct results but silently falls back to a plain sort. Vector columns inside ParadeDB indexes require pg_search 0.25.0+ (unreleased); the plain `vector(n)` column type and distance expressions work on any ParadeDB or Postgres with pgvector.
 
 ## Examples
 

examples/README.md

@@ -121,10 +121,9 @@ Structure:
 
 1. Vector Search (`vector_search/`)
 
-Top-K vector search inside the BM25 index: `vector(n)` columns, metric
-opclasses, and `nearest` queries. Requires a ParadeDB build with bm25 vector
-opclasses (not yet in a released ParadeDB version); the setup script aborts
-with a clear message otherwise.
+Top-K vector search inside the ParadeDB index: `vector(n)` columns, metric
+opclasses, and `nearest` queries. Requires pg_search 0.25.0+ (unreleased);
+the setup script aborts with a clear message otherwise.
 
 ```bash
 BUNDLE_GEMFILE=examples/Gemfile bundle exec ruby examples/vector_search/setup.rb

examples/hybrid_rrf/hybrid_rrf.rb

@@ -134,7 +134,7 @@ def display_results(query, rows)
   puts "=" * 80
   puts "Hybrid Search with Reciprocal Rank Fusion (single SQL query)"
   puts "=" * 80
-  puts "\nCombining ParadeDB BM25 + native vector distance in one CTE-based query"
+  puts "\nCombining ParadeDB BM25 + vector distance in one CTE-based query"
 
   HybridRrfSetup.setup!
   MockItem.reset_column_information

examples/vector_search/setup.rb

@@ -50,14 +50,17 @@ def connect!
     ActiveRecord::Base.logger = nil
   end
 
-  def vector_search_supported?
-    ActiveRecord::Base.connection.select_value(<<~SQL)
-      SELECT 1
+  # Prefer the paradedb access method when its vector opclasses exist,
+  # otherwise fall back to bm25; nil when the server has no vector opclasses.
+  def vector_index_am
+    ams = ActiveRecord::Base.connection.select_values(<<~SQL)
+      SELECT am.amname
       FROM pg_opclass oc
       JOIN pg_am am ON am.oid = oc.opcmethod
-      WHERE am.amname = 'bm25' AND oc.opcname = 'vector_l2_ops'
-      LIMIT 1
+      WHERE am.amname IN ('paradedb', 'bm25') AND oc.opcname = 'vector_l2_ops'
     SQL
+
+    ams.include?("paradedb") ? "paradedb" : ams.first
   end
 
   def setup!
@@ -67,10 +70,12 @@ def setup!
     conn.execute("CREATE EXTENSION IF NOT EXISTS pg_search;")
     conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
 
-    unless vector_search_supported?
-      abort "This example requires a ParadeDB build with bm25 vector opclasses " \
-            "(unreleased; see paradedb/paradedb branch mvp/vector-search)."
+    am = vector_index_am
+    unless am
+      abort "This example requires vector opclasses for the paradedb/bm25 access methods " \
+            "(pg_search 0.25.0+, unreleased)."
     end
+    VectorItemIndex.am = am
 
     conn.execute("DROP TABLE IF EXISTS vector_items CASCADE;")
     ActiveRecord::Schema.define do

examples/vector_search/vector_search.rb

@@ -58,11 +58,12 @@ class VectorItemIndex < ParadeDB::Index
     end
   end
 
-  it "runs Top-K vector search through the bm25 index" do
-    skip_unless_bm25_vector_support!
+  it "runs Top-K vector search through the ParadeDB index" do
+    skip_unless_vector_index_support!
 
     conn = ActiveRecord::Base.connection
-    conn.remove_bm25_index(:vector_items, if_exists: true)
+    conn.remove_paradedb_index(:vector_items, if_exists: true)
+    VectorItemIndex.am = vector_index_am
     conn.create_paradedb_index(VectorItemIndex)
 
     labels = VectorItem.nearest(:embedding, [1, 0, 0]).limit(2).pluck(:label)
@@ -75,26 +76,28 @@ class VectorItemIndex < ParadeDB::Index
                          .pluck(:label)
     assert_equal ["near x"], filtered
   ensure
-    ActiveRecord::Base.connection.remove_bm25_index(:vector_items, if_exists: true)
+    ActiveRecord::Base.connection.remove_paradedb_index(:vector_items, if_exists: true)
   end
 
   it "round-trips vector opclasses through the schema dumper" do
-    skip_unless_bm25_vector_support!
+    skip_unless_vector_index_support!
 
     conn = ActiveRecord::Base.connection
-    conn.remove_bm25_index(:vector_items, if_exists: true)
+    conn.remove_paradedb_index(:vector_items, if_exists: true)
 
+    am = vector_index_am
     cosine_index = Class.new(ParadeDB::Index) do
       self.table_name = :vector_items
       self.key_field = :id
+      self.am = am
       self.fields = { id: {}, label: {}, embedding: { metric: :cosine } }
     end
     conn.create_paradedb_index(cosine_index)
 
     output = dump_schema
-    assert_match(/add_bm25_index :vector_items,.*embedding: \{ metric: :cosine \}/, output)
+    assert_match(/add_paradedb_index :vector_items,.*embedding: \{ metric: :cosine \}/, output)
   ensure
-    ActiveRecord::Base.connection.remove_bm25_index(:vector_items, if_exists: true)
+    ActiveRecord::Base.connection.remove_paradedb_index(:vector_items, if_exists: true)
   end
 
   private
@@ -109,24 +112,27 @@ def pgvector_available?
     )
   end
 
-  def bm25_vector_search_supported?
-    ActiveRecord::Base.connection.select_value(<<~SQL)
-      SELECT 1
+  def vector_opclass_ams
+    @vector_opclass_ams ||= ActiveRecord::Base.connection.select_values(<<~SQL)
+      SELECT am.amname
       FROM pg_opclass oc
       JOIN pg_am am ON am.oid = oc.opcmethod
-      WHERE am.amname = 'bm25' AND oc.opcname = 'vector_l2_ops'
-      LIMIT 1
+      WHERE am.amname IN ('paradedb', 'bm25') AND oc.opcname = 'vector_l2_ops'
     SQL
   end
 
-  def skip_unless_bm25_vector_support!
-    return if bm25_vector_search_supported?
+  def vector_index_am
+    vector_opclass_ams.include?(paradedb_test_am) ? paradedb_test_am : vector_opclass_ams.first
+  end
+
+  def skip_unless_vector_index_support!
+    return if vector_index_am
 
     version = ActiveRecord::Base.connection.select_value(
       "SELECT extversion FROM pg_extension WHERE extname = 'pg_search'"
     )
-    skip "pg_search #{version} has no bm25 vector opclasses; vector-in-bm25 support " \
-         "is unreleased (paradedb/paradedb branch mvp/vector-search)"
+    skip "pg_search #{version} has no vector opclasses for the paradedb/bm25 access methods; " \
+         "vector-in-index support requires pg_search 0.25.0+ (unreleased)"
   end
 
   def ensure_vector_schema!

spec/vector_search_integration_spec.rb

@@ -140,14 +140,14 @@ def sql(node)
     assert_equal "embedding", entry.query_key
   end
 
-  it "emits opclasses in bm25 index DDL" do
+  it "emits opclasses in index DDL" do
     sql = ActiveRecord::Base.connection.send(
       :build_create_sql, VectorSearchProductIndex.compiled_definition, if_not_exists: false
     )
 
     assert_sql_equal <<~SQL, sql
       CREATE INDEX vector_search_products_bm25_idx ON products
-      USING bm25 (id, description, embedding vector_cosine_ops)
+      USING paradedb (id, description, embedding vector_cosine_ops)
       WITH (key_field='id')
     SQL
   end
@@ -207,7 +207,7 @@ def sql(node)
     recorder = Class.new do
       attr_reader :captured
 
-      def add_bm25_index(table, fields:, key_field:, name:, **)
+      def add_paradedb_index(table, fields:, key_field:, name:, **)
         @captured = { table: table, fields: fields, key_field: key_field, name: name }
       end
     end.new