full_search 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01b6db287587e57e3bc4f7226eff10257303eadf30c6a6a64e53be1e2e52afb5
-  data.tar.gz: 01ec5e01cf2d479245338c5a7ab23f778a9f953c78c7a0a1ab4f428a4472c98c
+  metadata.gz: d25d24145bf1aef1508210eb9d6879b21218ed8760ef6a61812706720a12ac17
+  data.tar.gz: 94b71b2b86db367ef8fde640550ab7b5945b50829d618c5e4eb41a4d9a6e0d65
 SHA512:
-  metadata.gz: 6a3bd6143a47be3e7abd89df28506f247ee562205372ee9b5bedf6064d463413e212b7bca67dffb3e980531963e55984750adfed5504cf70b7e0dc7fa250185b
-  data.tar.gz: 3b793c3bfd872cf1a247a18c030ade28433d16d40bc71438d35dc79be2cd306d15ec79f0afc371c0866ef9feeca8d3292ed9f8af35c9bb6c572b8073be88a12b
+  metadata.gz: 4074fd91514f5f209cbf6d5f4b2fdd36eed20ccfd894e0ccaac330e25bf7e0cda0c2c689833f2fcf947df768cf0282e88d717f1a001797e901ee0ebb18ab6e1a
+  data.tar.gz: f16291785a67d4e9cec7e48fe407a3c4735e21711752feea5ff2ad88573ef8010732feb8eaa9a1f1c40bfb14c14f476dd5f242fb9e624ba68f1a4ec18ca077ba

data/README.md

@@ -29,6 +29,13 @@ bundle install
 bin/rails generate full_search:install
 ```
 
+This creates the initializer and automatically runs `full_search:prepare` to create FTS tables.
+Use `--skip-prepare` if your database isn't ready yet:
+
+```bash
+bin/rails generate full_search:install --skip-prepare
+```
+
 ## Usage
 
 ```ruby
@@ -96,6 +103,34 @@ end
 
 This is enforced at the database level — the FTS virtual table only contains rows matching the condition, and triggers skip inserts/updates for non-matching records.
 
+### Exact match
+
+For exact-match lookups on encrypted identifiers or fields that need precise matching outside the FTS tokenizer, use `exact_match`:
+
+```ruby
+class Customer < ApplicationRecord
+  full_search do
+    field :first_name, weight: 5
+    filter :account_id, required: true
+
+    exact_match :customer_number
+  end
+end
+```
+
+```ruby
+Customer.search("CUST-001", filters: { account_id: 1 })
+# same query but only returns exact matches on customer_number
+```
+
+For case- or punctuation-normalized SQL exact matches, pass a `normalize` lambda that transforms the query the same way the SQL expression transforms the column:
+
+```ruby
+exact_match :license_plate,
+  sql: "UPPER(REPLACE(REPLACE(license_plate, ' ', ''), '-', ''))",
+  normalize: ->(q) { q.to_s.upcase.gsub(/[ -]/, "") }
+```
+
 ### Per-model operations
 
 Once a model declares `full_search`, you can call these class methods:
@@ -288,6 +323,44 @@ end
 
 `typo_tolerance` uses an FTS5 trigram shadow table as a fallback when the primary index returns no results. It is substring/trigram fallback, not edit-distance correction, and requires SQLite >= 3.34.
 
+You can disable the expensive `LIKE 'term%'` fallback for very short queries:
+
+```ruby
+full_search do
+  typo_tolerance
+  min_like_prefix_length 3
+end
+```
+
+## Multi-search
+
+Search across multiple models in a single call with `FullSearch.multi_search`:
+
+```ruby
+results = FullSearch.multi_search(
+  query: "Honda",
+  groups: [
+    {key: :customers, label: "Customers", model: Customer, filters: {account_id: 1}},
+    {key: :vehicles,  label: "Vehicles",  model: Vehicle,  filters: {account_id: 1}}
+  ]
+)
+
+results[:customers] #=> [#<Customer...>, ...]
+results[:vehicles]  #=> [#<Vehicle...>, ...]
+```
+
+Pass `includes:` to eager-load associations for each group:
+
+```ruby
+FullSearch.multi_search(
+  query: "Honda",
+  groups: [
+    {key: :vehicles, label: "Vehicles", model: Vehicle,
+     filters: {account_id: 1}, includes: [:customer]}
+  ]
+)
+```
+
 ## Known limitations
 
 - Queries run with `highlight: true` return an Array of records, not an `ActiveRecord::Relation`. No further chaining (`.where`, `.order`, `.limit`) is possible after highlighting is applied.

data/lib/full_search/config.rb

@@ -4,7 +4,7 @@ module FullSearch
   class Config
     attr_accessor :auto_rebuild_schema, :stale_query_behavior, :lock_rebuilds,
       :default_async_reindex, :default_async_source_reindex,
-      :default_tokenizer, :auto_rebuild_on_stale_query
+      :default_tokenizer, :auto_rebuild_on_stale_query, :min_like_prefix_length
 
     def initialize
       @auto_rebuild_schema = false
@@ -14,6 +14,7 @@ module FullSearch
       @default_async_source_reindex = true
       @default_tokenizer = "unicode61"
       @auto_rebuild_on_stale_query = false
+      @min_like_prefix_length = 3
     end
   end
 

data/lib/full_search/dsl.rb

@@ -5,7 +5,7 @@ module FullSearch
     attr_reader :fields, :exact_matches, :filters, :model_class, :highlight_config, :rank_bys, :index_if_sql
 
     Field = Data.define(:name, :weight, :source, :reindex_on, :async, :async_source, :as, :version)
-    ExactMatch = Data.define(:name, :source, :sql, :version)
+    ExactMatch = Data.define(:name, :source, :sql, :version, :normalize)
     Filter = Data.define(:name, :required)
     RankBy = Data.define(:column, :direction)
 
@@ -39,13 +39,13 @@ module FullSearch
       )
     end
 
-    def exact_match(name, source: -> { public_send(name) }, sql: nil, version: nil)
+    def exact_match(name, source: -> { public_send(name) }, sql: nil, normalize: nil, version: nil)
       unless valid_name?(name)
         raise InvalidFieldError, "#{model_class.name}: invalid exact_match name #{name.inspect}"
       end
       str = name.to_s
       raise InvalidFieldError, "#{model_class.name}: duplicate exact_match name #{name.inspect}" if exact_matches.any? { |e| e.name == str }
-      @exact_matches << ExactMatch.new(name: str, source: source, sql: sql&.to_s, version: version)
+      @exact_matches << ExactMatch.new(name: str, source: source, sql: sql&.to_s, normalize: normalize, version: version)
     end
 
     def rank_by(column, direction = :desc)
@@ -99,6 +99,14 @@ module FullSearch
       @index_if_sql.present?
     end
 
+    def min_like_prefix_length(value = :_no_arg_)
+      if value == :_no_arg_
+        @min_like_prefix_length ||= FullSearch.config.min_like_prefix_length
+      else
+        @min_like_prefix_length = value.to_i
+      end
+    end
+
     def typo_tolerance(enabled = true, min_term_length: nil)
       @typo_tolerance = enabled
       @typo_tolerance_min_term_length = min_term_length || 3
@@ -124,7 +132,8 @@ module FullSearch
         fields.map { |f| [f.name, f.weight, f.source.nil? ? "column" : "proc:#{f.version}", f.reindex_on, f.async, f.async_source, f.as] },
         exact_matches.map { |e| [e.name, "proc:#{e.version}", e.sql] },
         filters.map { |f| [f.name, f.required] },
-        rank_bys.map { |r| [r.column, r.direction] }
+        rank_bys.map { |r| [r.column, r.direction] },
+        min_like_prefix_length
       ].inspect)
     end
 

data/lib/full_search/exact_match.rb

@@ -19,7 +19,8 @@ module FullSearch
         filters.each { |name, value| base = base.where(name => value) }
 
         conditions = sql_matches.map do |em|
-          "(#{em.sql}) = #{model.connection.quote(cleaned)}"
+          value = em.normalize ? em.normalize.call(cleaned) : cleaned
+          "(#{em.sql}) = #{model.connection.quote(value)}"
         end.join(" OR ")
 
         ids += base.where(conditions).pluck(:id)

data/lib/full_search/index.rb

@@ -55,6 +55,7 @@ module FullSearch
       end
 
       def rebuild!(model)
+        IndexCache.clear!
         sqlite!(model)
 
         dsl = model.full_search_dsl
@@ -83,6 +84,7 @@ module FullSearch
       end
 
       def rebuild_if_needed!(model)
+        IndexCache.clear!
         sqlite!(model)
 
         dsl = model.full_search_dsl
@@ -137,6 +139,7 @@ module FullSearch
       end
 
       def drop!(model)
+        IndexCache.clear!
         verified_tables.delete(model.table_name)
         sqlite!(model)
         drop_triggers!(model)
@@ -168,10 +171,12 @@ module FullSearch
       end
 
       def stored_config_hash(model)
-        row = connection.execute(
-          "SELECT config_hash FROM full_search_index_versions WHERE table_name=#{q(model.table_name)}"
-        ).first
-        row&.[]("config_hash")
+        IndexCache.fetch("stored_config_hash:#{model.table_name}") do
+          row = connection.execute(
+            "SELECT config_hash FROM full_search_index_versions WHERE table_name=#{q(model.table_name)}"
+          ).first
+          row&.[]("config_hash")
+        end
       end
 
       def missing_table?(model)
@@ -207,9 +212,11 @@ module FullSearch
       end
 
       def table_exists?(model)
-        connection.execute(
-          "SELECT name FROM sqlite_master WHERE type='table' AND name=#{q(fts_table_name(model))} LIMIT 1"
-        ).any?
+        IndexCache.fetch("table_exists:#{model.table_name}") do
+          connection.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=#{q(fts_table_name(model))} LIMIT 1"
+          ).any?
+        end
       end
 
       def create_metadata_table!

data/lib/full_search/index_cache.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FullSearch
+  class IndexCache
+    def self.with_cache
+      already_cached = !Thread.current[:full_search_index_cache].nil?
+      Thread.current[:full_search_index_cache] ||= {}
+      yield
+    ensure
+      Thread.current[:full_search_index_cache] = nil unless already_cached
+    end
+
+    def self.clear!
+      Thread.current[:full_search_index_cache] = nil
+    end
+
+    def self.fetch(key)
+      cache = Thread.current[:full_search_index_cache]
+      return yield unless cache
+      return cache[key] if cache.key?(key)
+      cache[key] = yield
+    end
+  end
+end

data/lib/full_search/model.rb

@@ -5,7 +5,7 @@ module FullSearch
     extend ActiveSupport::Concern
 
     class_methods do
-      def full_search(query_or_options = nil, filters: {}, include_soft_deleted: false, limit: nil, offset: nil, highlight: false, highlight_fields: false, matching_strategy: nil, per_strategy_limit: nil, &block)
+      def full_search(query_or_options = nil, filters: {}, include_soft_deleted: false, limit: nil, offset: nil, highlight: false, highlight_fields: false, matching_strategy: nil, per_strategy_limit: nil, scope: nil, includes: nil, &block)
         if block_given? || query_or_options.is_a?(Hash)
           @full_search_dsl ||= FullSearch::Dsl.new(self)
           @full_search_dsl.tokenize(query_or_options[:tokenize]) if query_or_options.is_a?(Hash) && query_or_options.key?(:tokenize)
@@ -16,7 +16,7 @@ module FullSearch
           FullSearch.register_model(self)
           @full_search_dsl
         else
-          FullSearch::Search.new(self, query_or_options, filters: filters, include_soft_deleted: include_soft_deleted, limit: limit, offset: offset, highlight: highlight, highlight_fields: highlight_fields, matching_strategy: matching_strategy, per_strategy_limit: per_strategy_limit).relation
+          FullSearch::Search.new(self, query_or_options, filters: filters, include_soft_deleted: include_soft_deleted, limit: limit, offset: offset, highlight: highlight, highlight_fields: highlight_fields, matching_strategy: matching_strategy, per_strategy_limit: per_strategy_limit, scope: scope, includes: includes).relation
         end
       end
 

data/lib/full_search/multi_search.rb

@@ -29,11 +29,11 @@ module FullSearch
           highlight: group[:highlight],
           highlight_fields: group[:highlight_fields],
           matching_strategy: group[:matching_strategy],
-          per_strategy_limit: group[:per_strategy_limit]
+          per_strategy_limit: group[:per_strategy_limit],
+          scope: group[:scope],
+          includes: group[:includes]
         )
 
-        relation = group[:scope].call(relation) if group[:scope]
-
         records = relation.to_a
         has_more = records.size > limit
         records = records.first(limit) if has_more

data/lib/full_search/search.rb

@@ -2,9 +2,9 @@
 
 module FullSearch
   class Search
-    attr_reader :model, :query, :filters, :include_soft_deleted, :limit, :offset, :highlight, :highlight_fields, :matching_strategy, :per_strategy_limit
+    attr_reader :model, :query, :filters, :include_soft_deleted, :limit, :offset, :highlight, :highlight_fields, :matching_strategy, :per_strategy_limit, :scope, :includes
 
-    def initialize(model, query, filters:, include_soft_deleted:, limit:, offset:, highlight: false, highlight_fields: false, matching_strategy: nil, per_strategy_limit: nil)
+    def initialize(model, query, filters:, include_soft_deleted:, limit:, offset:, highlight: false, highlight_fields: false, matching_strategy: nil, per_strategy_limit: nil, scope: nil, includes: nil)
       @model = model
       @query = query.to_s.strip
       @filters = filters
@@ -15,6 +15,8 @@ module FullSearch
       @highlight_fields = highlight_fields
       @matching_strategy = matching_strategy
       @per_strategy_limit = per_strategy_limit
+      @scope = scope
+      @includes = includes
     end
 
     MIN_TERM_LENGTH = 3
@@ -37,10 +39,11 @@ module FullSearch
 
       rel = model.where(id: all_ids)
       rel = rel.where(model.arel_table[dsl.soft_delete_column].eq(nil)) if dsl.soft_delete_column && !include_soft_deleted
+      rel = apply_ranking(rel, all_ids, exact_ids)
+      rel = scope.call(rel) if scope
       rel = rel.limit(limit) if limit
       rel = rel.offset(offset) if offset
-
-      rel = apply_ranking(rel, all_ids, exact_ids)
+      rel = rel.includes(includes) if includes
 
       if highlight
         records = rel.to_a
@@ -84,7 +87,7 @@ module FullSearch
 
       stored = begin
         FullSearch::Index.stored_config_hash(model)
-      rescue StandardError
+      rescue
         nil
       end
       return unless stored
@@ -137,6 +140,7 @@ module FullSearch
       return [] if term.nil?
 
       if term.length < dsl.typo_tolerance_min_term_length.to_i
+        return [] if term.length < dsl.min_like_prefix_length
         return like_prefix_ids(term, candidate_limit: candidate_limit)
       end
 
@@ -162,6 +166,8 @@ module FullSearch
     end
 
     def like_prefix_ids(term, candidate_limit: nil)
+      return [] if term.to_s.length < dsl.min_like_prefix_length
+
       column_fields = dsl.fields.select { |f| f.source.nil? }
       source_fields = dsl.fields.select { |f| f.source }
       tbl = qt(model.table_name)

data/lib/full_search/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FullSearch
-  VERSION = "0.3.6"
+  VERSION = "0.3.7"
 end

data/lib/full_search.rb

@@ -4,6 +4,7 @@ require "active_record"
 require "active_support"
 require "active_support/concern"
 
+require "full_search/index_cache"
 require "full_search/version"
 require "full_search/config"
 require "full_search/distance"

data/lib/generators/full_search/install/install_generator.rb

@@ -7,9 +7,22 @@ module FullSearch
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
+      class_option :skip_prepare, type: :boolean, default: false,
+        desc: "Skip automatic full_search:prepare"
+
       def create_initializer
         template "full_search.rb", "config/initializers/full_search.rb"
       end
+
+      def prepare_indexes
+        return if options[:skip_prepare]
+
+        say "Running full_search:prepare to create FTS tables..."
+        rake("full_search:prepare")
+      rescue => e
+        say "Skipping full_search:prepare — #{e.message}", :yellow
+        say "Run `bin/rails full_search:prepare` after your database is ready.", :yellow
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: full_search
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.7
 platform: ruby
 authors:
 - Ben D'Angelo
@@ -150,6 +150,7 @@ files:
 - lib/full_search/exact_match.rb
 - lib/full_search/highlighter.rb
 - lib/full_search/index.rb
+- lib/full_search/index_cache.rb
 - lib/full_search/model.rb
 - lib/full_search/multi_search.rb
 - lib/full_search/optimize_job.rb