rails-paradedb 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f119945534d0ec4f358a9e05d85529d645dbd71e249a0456e65bbd70a7d63135
-  data.tar.gz: 7a9f56fe0eb2a0ea452697f90beeca5a58ca55b996c199fc08babbb14f10eb0c
+  metadata.gz: 04a77503859e70b3362f1a5679a2d1b229c62c5c49a0383fbe1164b317d902f2
+  data.tar.gz: 1ec3bc0ae18c1232ddfc1b67aec6eb3a92dde0285297fa4a45afa7b789ae9d7c
 SHA512:
-  metadata.gz: 1f98449702f8795645745b81bc344a1264946f8928e7bef804295a3bd15e468677414c85b266b2983ceb46aa558d9494f7933e0f770757cb0e31ff1d5fa39567
-  data.tar.gz: 3c2e6e60585532b13f3f810160ea77684274a1ba9ad7d7e878d037602bdb784edb2dbe773b66a87e21651671be121c3ba948fd7be38ee4e341c13ec151b7d1bd
+  metadata.gz: e81872356be536dd22423f39c7c8a899630dd5a601d5c54c6a8cbfc2c165ba3aa1c8edbe016a88ff9bc3492fcb0925c35cf31055dbca39de59f05f1b49ce2cec
+  data.tar.gz: 0c3781ba0d93f5aa4067545354f87e186da71c43fab1a257c9715ce821dfde474549c200d22f9814f75747a687a7e21626148de2b474759bc9317395f413902f

data/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-14
+
+### Added
+
+- Support partial indexes via `where:` in `add_bm25_index` and `ParadeDB::Index`
+
+### Fixed
+
+- Allow aliased indexed expressions like `"(rating + 1)" => { alias: "rating" }`
+
+## [0.4.0] - 2026-04-09
+
+### Changed
+
+- Removed unnecessary validation from non-exact aggregate queries without `over()`
+- `change` migrations now auto-reverse `create_paradedb_index` and `add_bm25_index`, while irreversible ParadeDB migration helpers raise explicit rollback errors
+
 ## [0.3.0] - 2026-03-23
 
 ### Removed
@@ -103,7 +120,9 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/paradedb/rails-paradedb/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.5.0
+[0.4.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.4.0
 [0.3.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.3.0
 [0.2.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.2.0
 [0.1.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.1.0

data/lib/parade_db/index.rb

@@ -3,7 +3,7 @@
 module ParadeDB
   class Index
     class << self
-      attr_writer :table_name, :key_field, :index_name, :fields, :index_options
+      attr_writer :table_name, :key_field, :index_name, :fields, :index_options, :where
 
       def table_name
         @table_name
@@ -25,6 +25,10 @@ module ParadeDB
         @index_options || {}
       end
 
+      def where
+        @where
+      end
+
       def default_index_name
         return nil if table_name.nil?
 
@@ -166,15 +170,16 @@ module ParadeDB
       FIELD_OPTION_KEYS = %i[fast record normalizer expand_dots].freeze
 
       class Compiled
-        attr_reader :table_name, :key_field, :index_name, :entries, :index_options, :field_options
+        attr_reader :table_name, :key_field, :index_name, :entries, :index_options, :field_options, :where
 
-        def initialize(table_name:, key_field:, index_name:, entries:, index_options:, field_options:)
+        def initialize(table_name:, key_field:, index_name:, entries:, index_options:, field_options:, where:)
           @table_name = table_name
           @key_field = key_field
           @index_name = index_name
           @entries = entries
           @index_options = index_options
           @field_options = field_options
+          @where = where
         end
       end
       Entry = Struct.new(:source, :expression, :tokenizer, :options, :query_key, keyword_init: true)
@@ -203,7 +208,8 @@ module ParadeDB
             index_name: index_name,
             entries: entries,
             index_options: index_options,
-            field_options: field_options
+            field_options: field_options,
+            where: klass.where
           )
         end
 
@@ -223,10 +229,6 @@ module ParadeDB
             raise InvalidIndexDefinition, "fields must be a Hash"
           end
 
-          build_entries_from_structured_fields(raw_fields)
-        end
-
-        def build_entries_from_structured_fields(raw_fields)
           entries = []
           field_options = {}
 
@@ -246,7 +248,16 @@ module ParadeDB
             tokenizers = normalized[:tokenizers]
             single_tokenizer_keys_present = TokenizerParser::TOKENIZER_SINGLE_KEYS.any? { |key| normalized.key?(key) }
 
-            if tokenizers
+            is_alias = normalized[:alias] && normalized.length == 1
+            if is_alias
+              entries << Entry.new(
+                source: source_name,
+                expression: expression?(source_name),
+                tokenizer: nil,
+                options: {},
+                query_key: normalized[:alias]
+              )
+            elsif tokenizers
               if single_tokenizer_keys_present
                 raise InvalidIndexDefinition,
                       "field #{source_name.inspect} cannot mix :tokenizers with :tokenizer/:args/:named_args/:filters/:stemmer/:alias"

data/lib/parade_db/migration_helpers.rb

@@ -21,7 +21,7 @@ module ParadeDB
       remember_schema_index_reference(resolved)
     end
 
-    def add_bm25_index(table, fields:, key_field:, name: nil, index_options: nil, if_not_exists: false)
+    def add_bm25_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, if_not_exists: false)
       ensure_postgresql_adapter!
       anonymous = Class.new(ParadeDB::Index)
       anonymous.table_name = table
@@ -29,6 +29,7 @@ module ParadeDB
       anonymous.index_name = name unless name.nil?
       anonymous.fields = fields
       anonymous.index_options = index_options unless index_options.nil?
+      anonymous.where = where unless where.nil?
 
       create_paradedb_index(anonymous, if_not_exists: if_not_exists)
     end
@@ -80,11 +81,12 @@ module ParadeDB
       prefix = if_not_exists ? "IF NOT EXISTS " : ""
       fields_sql = compiled.entries.map { |entry| bm25_entry_sql(entry) }.join(", ")
       with_options_sql = bm25_with_options_sql(compiled)
+      where_sql = compiled.where ? "\nWHERE #{compiled.where}" : ""
 
       <<~SQL.strip.gsub(/\s+/, " ")
         CREATE INDEX #{prefix}#{quote_table_name(compiled.index_name)} ON #{quote_table_name(compiled.table_name)}
         USING bm25 (#{fields_sql})
-        WITH (#{with_options_sql})
+        WITH (#{with_options_sql})#{where_sql}
       SQL
     end
 
@@ -177,6 +179,11 @@ module ParadeDB
 
     def bm25_entry_sql(entry)
       source_sql = bm25_source_sql(entry)
+
+      if entry.tokenizer.nil? && entry.query_key != entry.source
+        return "(#{source_sql}::pdb.alias(#{quote(entry.query_key)}))"
+      end
+
       return source_sql if entry.tokenizer.nil?
 
       "(#{source_sql}::#{tokenizer_sql(entry.tokenizer, entry.options)})"
@@ -282,7 +289,8 @@ module ParadeDB
         SELECT
           c.relname  AS index_name,
           t.relname  AS table_name,
-          pg_get_indexdef(c.oid) AS indexdef
+          pg_get_indexdef(c.oid) AS indexdef,
+          pg_get_expr(i.indpred, i.indrelid) AS where_clause
         FROM pg_class c
         JOIN pg_namespace n ON n.oid = c.relnamespace
         JOIN pg_index i ON i.indexrelid = c.oid
@@ -306,6 +314,7 @@ module ParadeDB
       key_field = extract_bm25_key_field(indexdef)
       index_options = extract_bm25_index_options(indexdef)
       fields_sql = extract_bm25_fields_sql(indexdef)
+      where = normalize_bm25_where_clause(row["where_clause"])
 
       if key_field && fields_sql
         field_sqls = split_bm25_top_level(fields_sql).map(&:strip)
@@ -334,6 +343,7 @@ module ParadeDB
         unless index_options.empty?
           statement += ", index_options: #{ruby_hash_literal(index_options)}"
         end
+        statement += ", where: #{where.inspect}" if where
         statement
       else
         "execute #{indexdef.inspect}"
@@ -351,10 +361,7 @@ module ParadeDB
     end
 
     def extract_bm25_index_options(indexdef)
-      with_match = indexdef.match(/WITH\s*\((.*)\)\s*\z/im)
-      return {} unless with_match
-
-      with_sql = with_match[1]
+      with_sql, = extract_bm25_with_components(indexdef)
       options = {}
       split_sql_arguments(with_sql).each do |argument|
         key, value_sql = split_assignment(argument)
@@ -378,7 +385,6 @@ module ParadeDB
 
     def extract_bm25_fields_sql(indexdef)
       match = indexdef.match(/USING\s+bm25\s*\(/im)
-      return nil unless match
 
       start = match.end(0)
       depth = 1
@@ -390,11 +396,61 @@ module ParadeDB
         end
         pos += 1
       end
-      return nil if depth != 0
+      raise "Found invalid index definition `#{indexdef}`" if depth != 0
 
       indexdef[start..pos - 2]
     end
 
+    def extract_bm25_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&.empty?
+
+      [with_sql, trailing_sql]
+    end
+
+    def normalize_bm25_where_clause(where)
+      return nil if where.nil?
+
+      normalized = where.to_s.strip
+      return nil if normalized.empty?
+
+      while bm25_wrapped_in_parentheses?(normalized)
+        normalized = normalized[1...-1].strip
+      end
+
+      normalized.empty? ? nil : normalized
+    end
+
+    def bm25_wrapped_in_parentheses?(sql)
+      return false unless sql.start_with?("(") && sql.end_with?(")")
+
+      depth = 0
+      sql.each_char.with_index do |char, idx|
+        case char
+        when "(" then depth += 1
+        when ")"
+          depth -= 1
+          return false if depth.zero? && idx < sql.length - 1
+        end
+      end
+
+      depth.zero?
+    end
+
     def split_bm25_top_level(str)
       parts = []
       current = +""
@@ -787,6 +843,42 @@ if defined?(ActiveRecord::ConnectionAdapters::AbstractAdapter)
   ActiveRecord::ConnectionAdapters::AbstractAdapter.include(ParadeDB::MigrationHelpers)
 end
 
+if defined?(ActiveRecord::Migration)
+  module ParadeDB
+    module MigrationDSL
+      def create_paradedb_index(index_klass, if_not_exists: false)
+        connection.create_paradedb_index(index_klass, if_not_exists: if_not_exists)
+      end
+
+      def replace_paradedb_index(index_klass)
+        connection.replace_paradedb_index(index_klass)
+      end
+
+      def add_bm25_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, if_not_exists: false)
+        connection.add_bm25_index(
+          table,
+          fields: fields,
+          key_field: key_field,
+          name: name,
+          index_options: index_options,
+          where: where,
+          if_not_exists: if_not_exists
+        )
+      end
+
+      def remove_bm25_index(table, name: nil, if_exists: false)
+        connection.remove_bm25_index(table, name: name, if_exists: if_exists)
+      end
+
+      def reindex_bm25(table, name: nil, concurrently: false)
+        connection.reindex_bm25(table, name: name, concurrently: concurrently)
+      end
+    end
+  end
+
+  ActiveRecord::Migration.include(ParadeDB::MigrationDSL)
+end
+
 if defined?(ActiveRecord::SchemaDumper)
   module ParadeDB
     module SchemaDumperPatch
@@ -829,3 +921,79 @@ if defined?(ActiveRecord::SchemaDumper)
 
   ActiveRecord::SchemaDumper.prepend(ParadeDB::SchemaDumperPatch)
 end
+
+if defined?(ActiveRecord::Migration::CommandRecorder)
+  module ParadeDB
+    module CommandRecorderPatch
+      %i[
+        create_paradedb_index
+        add_bm25_index
+        remove_bm25_index
+        replace_paradedb_index
+        reindex_bm25
+      ].each do |method_name|
+        define_method(method_name) do |*args, &block|
+          record(method_name, args, &block)
+        end
+        ruby2_keywords(method_name)
+      end
+
+      private
+
+      def invert_create_paradedb_index(args)
+        index_klass, = 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]]
+      end
+
+      def invert_add_bm25_index(args)
+        table, options = args
+        options = symbolize_options_hash(options)
+
+        remove_options = { if_exists: true }
+        remove_options[:name] = options[:name] if options[:name]
+        remove_options = Hash.ruby2_keywords_hash(remove_options)
+
+        [:remove_bm25_index, [table, remove_options]]
+      end
+
+      def invert_remove_bm25_index(_args)
+        raise ActiveRecord::IrreversibleMigration,
+              "remove_bm25_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."
+      end
+
+      def invert_reindex_bm25(_args)
+        raise ActiveRecord::IrreversibleMigration,
+              "reindex_bm25 is not automatically reversible. Use #up/#down or #reversible."
+      end
+
+      def resolve_paradedb_index_klass(index_klass)
+        case index_klass
+        when String
+          index_klass.to_s.split("::").inject(Object) { |ctx, const_name| ctx.const_get(const_name) }
+        else
+          index_klass
+        end
+      rescue NameError
+        raise ParadeDB::InvalidIndexDefinition, "Unknown index class #{index_klass.inspect}"
+      end
+
+      def symbolize_options_hash(options)
+        return {} unless options.is_a?(Hash)
+
+        options.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end
+      end
+    end
+  end
+
+  ActiveRecord::Migration::CommandRecorder.prepend(ParadeDB::CommandRecorderPatch)
+end

data/lib/parade_db/search_methods.rb

@@ -397,10 +397,6 @@ module ParadeDB
 
     def facets_agg(exact: nil, **named_aggregations)
       validate_exact_option!(exact)
-      if exact == false
-        raise ArgumentError, "facets_agg(exact: false) requires with_agg so aggregation runs as a window function"
-      end
-
       agg_specs = normalize_named_aggregation_specs(named_aggregations)
       build_aggregation_query(agg_specs, exact: exact).execute
     end

data/lib/parade_db/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ParadeDB
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-paradedb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ParadeDB