rails-paradedb 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296e696bfa9711537e984df359c43be2481b53a91f75c880dc33ac36aacf4b1c
-  data.tar.gz: 78781d5fc912c5b57053818d7f3e76e2d01251fb7d31a586edd5d28b88426e69
+  metadata.gz: 6cec3ad6c144476e82c57a3f9cba2b9ff497a838c34c032919b1eb785d4da435
+  data.tar.gz: 2af9e08e2bf7b9a12f9c005e99bc73f4a804f8a0c23f50c1fbc57637d6b87109
 SHA512:
-  metadata.gz: 5b4fecd2d8620a91e782ea62df980ab6638fec2906ad5a380664e97b77a8d0e1b4b656aa330cc4b9e80a99e18f2223cd2d50da6cea98245c63c1c4fe88ca7450
-  data.tar.gz: a6c42abf6b75aad3ee2d3b58651cfde545ba86deef7e33df0593cafc94da529818dbe41f290286e0acc3eb9bc62071d4d2b06d7976cb8c44d5a94be7c9a37722
+  metadata.gz: 1af9bfba690e6ba816fc5972f576885b72408594e68504e6d3bbf063944f6392debcf3cf7a028b5d08ba626d6acfaaeb7dbcb526db4adafa96cec987902fb6fa
+  data.tar.gz: 384b58ba9857bc2edb9a984ab71bd60d455daf5add4b3fc83b0c53458892496d21959b84e71680daddf7acc48f7c2832dbf930185661fb3ff587a22399a4bd84

data/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
-[0.10.0] - 2026-08-04
+## [0.12.0] - 2026-08-13
+
+### Changed
+
+- **BREAKING**: Search modifiers are now composable functions: `ParadeDB.boost`, `ParadeDB.constant`, `ParadeDB.fuzzy`, `ParadeDB.slop`, and `ParadeDB.tokenize`. Pass the wrapped value to search methods instead of using modifier keyword arguments.
+- **BREAKING**: Removed the public `ParadeDB::Arel` builder, Arel attribute predications, and `Model.paradedb_arel`. ParadeDB queries now use a private builder composed from standard Active Record nodes.
+
+## [0.11.0] - 2026-08-04
+
+### Added
+
+- Vector index build options `centroid_ratio`, `training_samples_per_centroid`, and `cluster_replication` in `ParadeDB::Index` `index_options` and `add_paradedb_index` (pg_search 0.25.0+). They are emitted in the `WITH (...)` clause and round-tripped through the schema dumper.
+
+## [0.10.0] - 2026-08-04
 
 ### Added
 
@@ -20,7 +33,7 @@ All notable changes to this project will be documented in this file. The format
 - **BREAKING**: Index creation always emits `USING paradedb`, which requires pg_search 0.25.0+. There is no option to select the legacy `bm25` access method.
 - **BREAKING**: The default index name is now `<table>_search_idx` (previously `<table>_bm25_idx`), and the index generator emits `Create<Model>SearchIndex` migrations named `create_<table>_search_index.rb`.
 
-[0.9.0] - 2026-07-14
+## [0.9.0] - 2026-07-14
 
 ### Added
 
@@ -170,7 +183,8 @@ All notable changes to this project will be documented in this file. The format
 - Schema dump/load round-trip for tokenizer configuration and index options
   (including `target_segment_count`)
 
-[Unreleased]: https://github.com/paradedb/rails-paradedb/compare/v0.10.0...HEAD
+[0.12.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.12.0
+[0.11.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.11.0
 [0.10.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.10.0
 [0.9.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.9.0
 [0.8.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.8.0

data/README.md

@@ -36,47 +36,45 @@
 
 ## 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 ParadeDB 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](https://guides.rubyonrails.org/active_record_basics.html) 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 search](https://docs.paradedb.com/documentation/full-text/overview) and [vector search](https://docs.paradedb.com/documentation/vector/overview) over pgvector `vector` types. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
 
 ## Requirements & Compatibility
 
-| Component  | Supported                                                         |
-| ---------- | ----------------------------------------------------------------- |
-| Ruby       | 3.2+                                                              |
-| Rails      | 7.2+                                                              |
-| ParadeDB   | 0.25.0+                                                           |
-| PostgreSQL | 15+ (PostgreSQL adapter with ParadeDB extension)                  |
-| pgvector   | Required for vector search; included in the ParadeDB Docker image |
-
-## Vector Search
-
-rails-paradedb supports full-text search and vector search over pgvector `vector(n)` columns. See the [vector search documentation](https://docs.paradedb.com/documentation/vector/overview) for details.
+| Component  | Supported                                                          |
+| ---------- | ------------------------------------------------------------------ |
+| Ruby       | 3.2+                                                               |
+| Rails      | 7.2+                                                               |
+| ParadeDB   | 0.25.0+                                                            |
+| PostgreSQL | 15+ (with the ParadeDB pg_search extension)                        |
+| pgvector   | Required for vector search (included in the ParadeDB Docker image) |
 
 ## Examples
 
 - [Quickstart](examples/quickstart/quickstart.rb)
 - [Vector Search](examples/vector_search/vector_search.rb)
 - [Faceted Search](examples/faceted_search/faceted_search.rb)
+- [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.rb)
+- [Retrieval-Augmented Generation (RAG)](examples/rag/rag.rb)
 - [Autocomplete](examples/autocomplete/autocomplete.rb)
 - [More Like This](examples/more_like_this/more_like_this.rb)
-- [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.rb)
-- [RAG](examples/rag/rag.rb)
+
+See [examples/README.md](examples/README.md) for setup instructions and a description of each example.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test commands, linting, and PR workflow.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, running tests, linting, and the PR workflow.
 
 ## Support
 
-If you're missing a feature or have found a bug, open a
+If you're missing a feature or have found a bug, please open a
 [GitHub Issue](https://github.com/paradedb/rails-paradedb/issues/new/choose).
 
-For community support:
+To get community support, you can:
 
-- Join the [ParadeDB Slack Community](https://paradedb.com/slack)
-- Ask in [ParadeDB Discussions](https://github.com/paradedb/paradedb/discussions)
+- Post a question in the [ParadeDB Slack Community](https://paradedb.com/slack)
+- Ask for help on our [GitHub Discussions](https://github.com/paradedb/paradedb/discussions)
 
-For commercial support, contact [sales@paradedb.com](mailto:sales@paradedb.com).
+If you need commercial support, please [contact the ParadeDB team](mailto:sales@paradedb.com).
 
 ## Acknowledgments
 

data/lib/parade_db/aggregations.rb

@@ -7,14 +7,7 @@ module ParadeDB
       # Backward-compatible reader for code that accessed `filtered_spec.filter`.
       alias filter agg_filter
     end
-    FieldTermFilter = Struct.new(
-      :field,
-      :term,
-      :distance,
-      :prefix,
-      :transposition_cost_one,
-      keyword_init: true
-    )
+    FieldTermFilter = Struct.new(:field, :term, keyword_init: true)
 
     TERMS_ORDER = {
       count_desc: { "_count" => "desc" },
@@ -154,16 +147,9 @@ module ParadeDB
       { "top_hits" => payload }
     end
 
-    def filtered(spec, filter: nil, field: nil, term: nil, distance: nil, prefix: nil, transposition_cost_one: nil)
+    def filtered(spec, filter: nil, field: nil, term: nil)
       normalized_spec = normalize_spec(spec)
-      normalized_filter = normalize_filter(
-        filter: filter,
-        field: field,
-        term: term,
-        distance: distance,
-        prefix: prefix,
-        transposition_cost_one: transposition_cost_one
-      )
+      normalized_filter = normalize_filter(filter: filter, field: field, term: term)
       FilteredSpec.new(spec: normalized_spec, agg_filter: normalized_filter)
     end
 
@@ -211,7 +197,7 @@ module ParadeDB
     end
     private_class_method :normalize_spec
 
-    def normalize_filter(filter:, field:, term:, distance:, prefix:, transposition_cost_one:)
+    def normalize_filter(filter:, field:, term:)
       if filter
         if !field.nil? || !term.nil?
           raise ArgumentError, "filtered aggregation accepts either filter: or field/term arguments, not both"
@@ -223,17 +209,7 @@ module ParadeDB
         raise ArgumentError, "filtered aggregation requires filter: or both field: and term:"
       end
 
-      normalized_distance = distance.nil? ? nil : normalize_non_negative_integer(distance, "distance")
-      normalized_prefix = normalize_boolean_option(prefix, "prefix")
-      normalized_transposition = normalize_boolean_option(transposition_cost_one, "transposition_cost_one")
-
-      FieldTermFilter.new(
-        field: normalize_field(field),
-        term: term,
-        distance: normalized_distance,
-        prefix: normalized_prefix,
-        transposition_cost_one: normalized_transposition
-      )
+      FieldTermFilter.new(field: normalize_field(field), term: term)
     end
     private_class_method :normalize_filter
 
@@ -318,14 +294,6 @@ module ParadeDB
     end
     private_class_method :normalize_sort_direction
 
-    def normalize_boolean_option(value, name)
-      return nil if value.nil?
-      return value if value == true || value == false
-
-      raise ArgumentError, "#{name} must be true, false, or nil"
-    end
-    private_class_method :normalize_boolean_option
-
     def deep_stringify(value)
       case value
       when Hash

data/lib/parade_db/index.rb

@@ -83,6 +83,8 @@ module ParadeDB
     # Consumed by migration helpers; validates and normalizes the DSL class
     class DefinitionCompiler
       FIELD_OPTION_KEYS = %i[fast record normalizer expand_dots].freeze
+      INDEX_OPTION_KEYS = %i[target_segment_count centroid_ratio training_samples_per_centroid cluster_replication].freeze
+      POSITIVE_INTEGER_INDEX_OPTION_KEYS = %i[target_segment_count training_samples_per_centroid cluster_replication].freeze
 
       class Compiled
         attr_reader :table_name, :key_field, :index_name, :entries, :index_options, :field_options, :where
@@ -238,16 +240,26 @@ module ParadeDB
             memo[key.to_sym] = value
           end
 
-          unknown = normalized.keys - [:target_segment_count]
+          unknown = normalized.keys - INDEX_OPTION_KEYS
           unless unknown.empty?
             raise InvalidIndexDefinition,
                   "unknown index_options keys: #{unknown.map(&:inspect).join(', ')}"
           end
 
-          if normalized.key?(:target_segment_count)
-            target = normalized[:target_segment_count]
-            unless target.is_a?(Integer) && target.positive?
-              raise InvalidIndexDefinition, "index_options[:target_segment_count] must be an Integer > 0"
+          POSITIVE_INTEGER_INDEX_OPTION_KEYS.each do |key|
+            next unless normalized.key?(key)
+
+            value = normalized[key]
+            unless value.is_a?(Integer) && value.positive?
+              raise InvalidIndexDefinition, "index_options[#{key.inspect}] must be an Integer > 0"
+            end
+          end
+
+          if normalized.key?(:centroid_ratio)
+            ratio = normalized[:centroid_ratio]
+            unless ratio.is_a?(Numeric) && ratio >= 0.000001 && ratio <= 1.0
+              raise InvalidIndexDefinition,
+                    "index_options[:centroid_ratio] must be a Numeric between 0.000001 and 1.0"
             end
           end
 

data/lib/parade_db/migration_helpers.rb

@@ -100,9 +100,12 @@ module ParadeDB
       options << "key_field=#{quote(compiled.key_field.to_s)}"
 
       compiled.index_options.each do |key, value|
-        case key.to_sym
-        when :target_segment_count
-          options << "target_segment_count=#{Integer(value)}"
+        name = key.to_sym
+        case name
+        when :target_segment_count, :training_samples_per_centroid, :cluster_replication
+          options << "#{name}=#{Integer(value)}"
+        when :centroid_ratio
+          options << "centroid_ratio=#{Float(value)}"
         else
           raise ParadeDB::InvalidIndexDefinition, "unsupported index option #{key.inspect}"
         end
@@ -297,6 +300,7 @@ module ParadeDB
           c.relname  AS index_name,
           t.relname  AS table_name,
           pg_get_indexdef(c.oid) AS indexdef,
+          array_to_json(c.reloptions)::text AS reloptions,
           pg_get_expr(i.indpred, i.indrelid) AS where_clause
         FROM pg_class c
         JOIN pg_namespace n ON n.oid = c.relnamespace
@@ -319,7 +323,7 @@ module ParadeDB
       name = row["index_name"]
 
       key_field = extract_paradedb_key_field(indexdef)
-      index_options = extract_paradedb_index_options(indexdef)
+      index_options = extract_paradedb_index_options(row["reloptions"])
       fields_sql = extract_paradedb_fields_sql(indexdef)
       where = normalize_paradedb_where_clause(row["where_clause"])
 
@@ -369,27 +373,30 @@ module ParadeDB
       nil
     end
 
-    def extract_paradedb_index_options(indexdef)
-      with_sql, = extract_paradedb_with_components(indexdef)
-      options = {}
-      split_sql_arguments(with_sql).each do |argument|
-        key, value_sql = split_assignment(argument)
-        next if key.nil?
-        next if key == "key_field"
+    def extract_paradedb_index_options(reloptions)
+      paradedb_reloption_entries(reloptions).each_with_object({}) do |entry, options|
+        key, separator, value = entry.to_s.partition("=")
+        next if separator.empty?
 
         case key
-        when "target_segment_count"
-          parsed = parse_sql_literal(value_sql)
-          if parsed.is_a?(Integer)
-            options[:target_segment_count] = parsed
-          elsif parsed.is_a?(String) && parsed.match?(/\A\d+\z/)
-            options[:target_segment_count] = parsed.to_i
-          end
+        when "target_segment_count", "training_samples_per_centroid", "cluster_replication"
+          parsed = Integer(value, 10, exception: false)
+          options[key.to_sym] = parsed if parsed
+        when "centroid_ratio"
+          parsed = Float(value, exception: false)
+          options[:centroid_ratio] = parsed if parsed
         end
       end
-      options
-    rescue
-      {}
+    end
+
+    def paradedb_reloption_entries(reloptions)
+      case reloptions
+      when Array then reloptions
+      when String then Array(JSON.parse(reloptions))
+      else []
+      end
+    rescue JSON::ParserError
+      []
     end
 
     def extract_paradedb_fields_sql(indexdef)
@@ -410,27 +417,6 @@ module ParadeDB
       indexdef[start..pos - 2]
     end
 
-    def extract_paradedb_with_components(indexdef)
-      match = indexdef.match(/WITH\s*\(/im)
-      start = match.end(0)
-      depth = 1
-      pos = start
-      while pos < indexdef.length && depth > 0
-        case indexdef[pos]
-        when "(" then depth += 1
-        when ")" then depth -= 1
-        end
-        pos += 1
-      end
-      raise "Found invalid index definition `#{indexdef}`" if depth != 0
-
-      with_sql = indexdef[start..pos - 2]
-      trailing_sql = indexdef[pos..]&.strip
-      trailing_sql = nil if trailing_sql == ""
-
-      [with_sql, trailing_sql]
-    end
-
     def normalize_paradedb_where_clause(where)
       return nil if where.nil?
 

data/lib/parade_db/model.rb

@@ -11,12 +11,14 @@ module ParadeDB
       :paradedb_search,
       :more_like_this,
       :nearest,
+      :l2_distance,
+      :cosine_distance,
+      :inner_product,
       :with_facets,
       :facets,
       :with_agg,
       :facets_agg,
       :aggregate_by,
-      :paradedb_arel,
       :paradedb_index,
       :paradedb_index_class,
       :paradedb_index_classes,
@@ -74,6 +76,21 @@ module ParadeDB
         all.extending(SearchMethods).nearest(column, vector, metric: metric)
       end
 
+      def l2_distance(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :l2)
+      end
+
+      def cosine_distance(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :cosine)
+      end
+
+      def inner_product(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :ip)
+      end
+
       def with_facets(*fields, **opts)
         ensure_postgres!
         paradedb_validate_index!
@@ -108,11 +125,6 @@ module ParadeDB
         )
       end
 
-      def paradedb_arel
-        ensure_postgres!
-        @paradedb_arel ||= ParadeDB::Arel::Builder.new(table_name)
-      end
-
       def paradedb_index(index_class)
         @paradedb_explicit_index_classes ||= []
         @paradedb_explicit_index_classes << index_class unless @paradedb_explicit_index_classes.include?(index_class)