rails-paradedb 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dac52ada2e15357193301cb0b3cf68bd0ef593794f972907c7ebf67cfa468f8
-  data.tar.gz: 99f3e0a8d0b18c1641e07bfe0e7098b2f19843de8910caa73c891b4ae3f42b9c
+  metadata.gz: 1bcba07642cf33fe747ed6f810374adee776ee014533e64f5b38d490335dd672
+  data.tar.gz: a470ac63132444ae93ee893eee869d6dac4641774fe965f6519592a7e5c50d35
 SHA512:
-  metadata.gz: 020ae66713435adf05815a48581f1793a47ce5fabc1fd1abb2667408c18f99435eb915dac14d78afd3b566166cde0deb83af5177caecb8c9382c2317f667a983
-  data.tar.gz: 66c366c60656a2f494aefd0c0b050ea6fb8bcc57e7f3d9be270a9dabe75745bbec12ec7561531196c17f71bc3e3c59769515c1b43bb43e7c2b3fe961433cecaa
+  metadata.gz: aa7193be8a40ed3714b3d17cf1c1b53980b63245a70c878e6aaa164c272df072217eb9c71a808cc29c0dc2611056f7d323f3d6aa9e507b77648beea83a734b6e
+  data.tar.gz: 6870426a910699fd8b1b12f7a03402d8157138d2b2aa4c210339356a2ff60299b29301a1a5cc28f64656f4e80479719e0324270dd0f5a9f7668e09ee9654a262

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-14
+
+### Added
+
+- Support concurrent BM25 index creation via `concurrently:` in `create_paradedb_index` and `add_bm25_index`
+
+## [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
@@ -110,7 +126,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.4.0...HEAD
+[Unreleased]: https://github.com/paradedb/rails-paradedb/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.6.0
+[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

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

@@ -6,7 +6,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Mi
 
 <% end -%>
   def up
-    create_paradedb_index(<%= class_name %>Index, if_not_exists: true)
+    create_paradedb_index(<%= class_name %>Index, if_not_exists: true<% if options[:concurrent] %>, concurrently: true<% end %>)
   end
 
   def down

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

@@ -4,11 +4,15 @@ require_relative "tokenizer_sql"
 
 module ParadeDB
   module MigrationHelpers
-    def create_paradedb_index(index_klass, if_not_exists: false)
+    def create_paradedb_index(index_klass, if_not_exists: false, concurrently: false)
       ensure_postgresql_adapter!
+      if concurrently && transaction_open_for_paradedb?
+        raise ArgumentError, "create_paradedb_index concurrently: true cannot run inside a transaction"
+      end
+
       resolved = resolve_index_klass(index_klass)
       compiled = resolved.compiled_definition
-      execute(build_create_sql(compiled, if_not_exists: if_not_exists))
+      execute(build_create_sql(compiled, if_not_exists: if_not_exists, concurrently: concurrently))
       remember_schema_index_reference(resolved)
     end
 
@@ -21,7 +25,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, concurrently: false)
       ensure_postgresql_adapter!
       anonymous = Class.new(ParadeDB::Index)
       anonymous.table_name = table
@@ -29,8 +33,9 @@ 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)
+      create_paradedb_index(anonymous, if_not_exists: if_not_exists, concurrently: concurrently)
     end
 
     def remove_bm25_index(table, name: nil, if_exists: false)
@@ -76,15 +81,17 @@ module ParadeDB
       ParadeDB.ensure_postgresql_adapter!(self, context: "ParadeDB migration helper")
     end
 
-    def build_create_sql(compiled, if_not_exists:)
+    def build_create_sql(compiled, if_not_exists:, concurrently: false)
+      modifier = concurrently ? " CONCURRENTLY" : ""
       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)}
+        CREATE INDEX#{modifier} #{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 +184,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 +294,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 +319,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 +348,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 +366,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 +390,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 +401,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 = +""
@@ -790,22 +851,24 @@ 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)
+      def create_paradedb_index(index_klass, if_not_exists: false, concurrently: false)
+        connection.create_paradedb_index(index_klass, if_not_exists: if_not_exists, concurrently: concurrently)
       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, if_not_exists: false)
+      def add_bm25_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, if_not_exists: false, concurrently: false)
         connection.add_bm25_index(
           table,
           fields: fields,
           key_field: key_field,
           name: name,
           index_options: index_options,
-          if_not_exists: if_not_exists
+          where: where,
+          if_not_exists: if_not_exists,
+          concurrently: concurrently
         )
       end
 

data/lib/parade_db/version.rb

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

metadata

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