full_search 0.3.6 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01b6db287587e57e3bc4f7226eff10257303eadf30c6a6a64e53be1e2e52afb5
-  data.tar.gz: 01ec5e01cf2d479245338c5a7ab23f778a9f953c78c7a0a1ab4f428a4472c98c
+  metadata.gz: a86070d05b32fc24ce6ac007a33c673c3831760ce76554bbb9d636e6e0c6be0f
+  data.tar.gz: 293b0be9931c7ffa5de9971aa52b2bf9014c2b0816d1364f839ccba57af8f814
 SHA512:
-  metadata.gz: 6a3bd6143a47be3e7abd89df28506f247ee562205372ee9b5bedf6064d463413e212b7bca67dffb3e980531963e55984750adfed5504cf70b7e0dc7fa250185b
-  data.tar.gz: 3b793c3bfd872cf1a247a18c030ade28433d16d40bc71438d35dc79be2cd306d15ec79f0afc371c0866ef9feeca8d3292ed9f8af35c9bb6c572b8073be88a12b
+  metadata.gz: cd9854cc22d14bd739723e5011a831fd34d0e523ef6a6df09bf45fa1f3a7880c466f4ba121eb07d9d92daf65449edf74b5e0ddc42dc15b521ea34e78b496be3a
+  data.tar.gz: f704e822cee03ad98f2ed96dbc802e3e5b777df659ecdc3d8187ace6088494ab318b6f1598c74b840697909b465e539a76ee9f758d6a709041d9e0b198d45129

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:
@@ -158,6 +193,20 @@ end
 
 ### In production
 
+**`auto_rebuild_schema`** — Must be `false` in production. The generated initializer defaults to `Rails.env.local?`, so it's already off. If enabled, every process (web, worker, console) attempts schema rebuilds on boot, which is unnecessary and can cause issues during zero-downtime deploys where old and new processes overlap.
+
+**`auto_rebuild_on_stale_query`** — Must be `false` in production. A query-time rebuild is dangerous — it can cause timeouts or race conditions under load. The generated initializer defaults to `Rails.env.local?`, keeping it off in production.
+
+**`lock_rebuilds`** — This option uses a Ruby `Mutex` and only prevents concurrent rebuilds within the same process. It does **not** coordinate across processes or hosts. Multi-process or multi-host deployments must run `full_search:rebuild` from a single deployment step.
+
+**Docker entrypoint** — For containerized environments, add `full_search:prepare` after `db:prepare:with_data`:
+
+```bash
+./bin/rails full_search:prepare
+```
+
+`full_search:prepare` is idempotent — it only creates missing FTS tables and installs triggers, making it safe to run on every deploy.
+
 Auto-rebuild runs on every Rails process boot (web, worker, console). For zero-downtime deploys where old processes still serve traffic, or if you prefer explicit control, set `auto_rebuild_schema` to `false` and run the rebuild task manually:
 
 ```bash
@@ -288,6 +337,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/backfill_job.rb

@@ -8,6 +8,7 @@ module FullSearch
 
     def perform(model_name)
       model = model_name.to_s.constantize
+      FullSearch::Index.sqlite!(model)
       FullSearch::Index.rebuild!(model)
     end
   end

data/lib/full_search/callbacks.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "full_search/errors"
+
 module FullSearch
   module Callbacks
     def self.install!(model)
@@ -64,34 +66,35 @@ module FullSearch
 
       value = FullSearch::Model.evaluate_source(record, field)
       table = qt(FullSearch::Index.fts_table_name(record.class))
-      conn = ActiveRecord::Base.connection
+      conn = connection_for(record.class)
       conn.execute(
         "UPDATE #{table} SET #{qc(field.as || field.name)} = #{q(value.to_s)} WHERE rowid = #{q(record.id)}"
       )
-    rescue => e
-      raise unless e.message.include?("no such table")
+    rescue ActiveRecord::StatementInvalid => e
+      raise_missing_table_or_original(e, record.class)
     end
 
     def self.remove_record!(record)
       table = qt(FullSearch::Index.fts_table_name(record.class))
-      conn = ActiveRecord::Base.connection
+      conn = connection_for(record.class)
       conn.execute("DELETE FROM #{table} WHERE rowid = #{q(record.id)}")
-    rescue => e
-      raise unless e.message.include?("no such table")
+    rescue ActiveRecord::StatementInvalid => e
+      raise_missing_table_or_original(e, record.class)
     end
 
     def self.reindex_dependents!(parent_record, dependent_model, field)
       fk = association_key(dependent_model, field.reindex_on)
-      conn = ActiveRecord::Base.connection
+      conn = connection_for(dependent_model)
       sql = "SELECT id FROM #{qt(dependent_model.table_name)} WHERE #{qc(fk)} = #{q(parent_record.id)}"
       dependent_ids = conn.execute(sql).map { |r| r["id"] }
 
-      dependent_ids.each do |dep_id|
-        if field.async
-          FullSearch::ReindexJob.perform_later(dependent_model.name, dep_id, field.name)
-        else
-          dependent = dependent_model.find_by(id: dep_id)
-          reindex_field!(dependent, field.name) if dependent
+      return if dependent_ids.empty?
+
+      if field.async
+        dependent_ids.each { |id| FullSearch::ReindexJob.perform_later(dependent_model.name, id, field.name) }
+      else
+        dependent_model.where(id: dependent_ids).find_each(batch_size: 500) do |record|
+          reindex_field!(record, field.name)
         end
       end
     end
@@ -113,5 +116,20 @@ module FullSearch
       reflection = model.reflect_on_association(association_name.to_sym)
       reflection&.foreign_key&.to_s || "#{association_name}_id"
     end
+
+    def self.connection_for(klass)
+      klass.connection
+    rescue NoMethodError
+      ActiveRecord::Base.connection
+    end
+
+    def self.raise_missing_table_or_original(error, model_class)
+      if error.message.include?("no such table")
+        FullSearch::Instrumentation.instrument("missing_table", model: model_class.name, error: error.message)
+        return
+      end
+      raise error
+    end
+    private_class_method :raise_missing_table_or_original
   end
 end

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
@@ -12,8 +12,9 @@ module FullSearch
       @lock_rebuilds = true
       @default_async_reindex = true
       @default_async_source_reindex = true
-      @default_tokenizer = "unicode61"
+      @default_tokenizer = FullSearch::Constants::DEFAULT_TOKENIZER
       @auto_rebuild_on_stale_query = false
+      @min_like_prefix_length = FullSearch::Constants::DEFAULT_MIN_LIKE_PREFIX_LENGTH
     end
   end
 

data/lib/full_search/constants.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FullSearch
+  module Constants
+    MIN_TERM_LENGTH = 3
+    TWO_TYPO_MIN_LENGTH = 9
+    DEFAULT_MIN_LIKE_PREFIX_LENGTH = 3
+    REBUILDING_HASH = "__rebuilding__"
+    DEFAULT_TOKENIZER = "unicode61"
+    MAX_EXACT_MATCH_BOOST_IDS = 100
+  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,15 @@ 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)
+      sql_str = sql&.to_s
+      validate_sql_fragment!(sql_str, "exact_match sql:") if sql_str
+      @exact_matches << ExactMatch.new(name: str, source: source, sql: sql_str, normalize: normalize, version: version)
     end
 
     def rank_by(column, direction = :desc)
@@ -92,16 +94,26 @@ module FullSearch
     end
 
     def index_if(sql: nil)
-      @index_if_sql = sql&.to_s
+      sql_str = sql&.to_s
+      validate_sql_fragment!(sql_str, "index_if sql:") if sql_str
+      @index_if_sql = sql_str
     end
 
     def conditional_index?
       @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
+      @typo_tolerance_min_term_length = min_term_length || FullSearch::Constants::MIN_TERM_LENGTH
     end
 
     def typo_tolerance?
@@ -109,7 +121,7 @@ module FullSearch
     end
 
     def typo_tolerance_min_term_length
-      @typo_tolerance_min_term_length || 3
+      @typo_tolerance_min_term_length || FullSearch::Constants::MIN_TERM_LENGTH
     end
 
     def config_hash
@@ -124,12 +136,19 @@ 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
 
     private
 
+    def validate_sql_fragment!(sql, option_name)
+      if sql.match?(/;|--|\/\*|\*\//)
+        raise InvalidFieldError, "#{model_class.name}: #{option_name} contains unsafe characters"
+      end
+    end
+
     def valid_name?(name)
       name.to_s.match?(/\A[a-zA-Z_]\w*\z/)
     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/highlighter.rb

@@ -59,7 +59,7 @@ module FullSearch
         length = query.length
         min_length = dsl.typo_tolerance_min_term_length.to_i
         return nil if length < min_length
-        return 2 if length >= 9
+        return 2 if length >= FullSearch::Constants::TWO_TYPO_MIN_LENGTH
         1
       end
 
@@ -170,8 +170,8 @@ module FullSearch
       end
 
       def max_allowed_typos(length)
-        return -1 if length < 3
-        return 2 if length >= 9
+        return -1 if length < FullSearch::Constants::MIN_TERM_LENGTH
+        return 2 if length >= FullSearch::Constants::TWO_TYPO_MIN_LENGTH
         1
       end
 

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
@@ -64,25 +65,28 @@ module FullSearch
         create_metadata_table!
 
         with_rebuild_lock(model) do
-          drop_triggers!(model)
-          conn.execute("DROP TABLE IF EXISTS #{qt(fts_table_name(model))};")
-          conn.execute("DROP TABLE IF EXISTS #{qt(trigram_table_name(model))};")
-          conn.execute(create_virtual_table_sql(model))
-          if dsl.typo_tolerance?
-            FullSearch::Typo.warn_unsupported!(model) unless FullSearch::Typo.supported?(model)
-            conn.execute(create_trigram_virtual_table_sql(model))
+          FullSearch::Instrumentation.instrument("rebuild", model: model.name) do
+            drop_triggers!(model)
+            conn.execute("DROP TABLE IF EXISTS #{qt(fts_table_name(model))};")
+            conn.execute("DROP TABLE IF EXISTS #{qt(trigram_table_name(model))};")
+            conn.execute(create_virtual_table_sql(model))
+            if dsl.typo_tolerance?
+              FullSearch::Typo.warn_unsupported!(model) unless FullSearch::Typo.supported?(model)
+              conn.execute(create_trigram_virtual_table_sql(model))
+            end
+            conn.execute(backfill_sql(model))
+            conn.execute(backfill_trigram_sql(model)) if dsl.typo_tolerance?
+            reindex_source_fields!(model) if dsl.fields.any?(&:source)
+            create_triggers!(model)
+            optimize!(model)
+            store_config_hash!(model, rebuilt_at: Time.current)
+            verified_tables.add(model.table_name)
           end
-          conn.execute(backfill_sql(model))
-          conn.execute(backfill_trigram_sql(model)) if dsl.typo_tolerance?
-          reindex_source_fields!(model) if dsl.fields.any?(&:source)
-          create_triggers!(model)
-          optimize!(model)
-          store_config_hash!(model, rebuilt_at: Time.current)
-          verified_tables.add(model.table_name)
         end
       end
 
       def rebuild_if_needed!(model)
+        IndexCache.clear!
         sqlite!(model)
 
         dsl = model.full_search_dsl
@@ -101,21 +105,35 @@ module FullSearch
       end
 
       def optimize!(model)
-        sqlite!(model)
-        connection.execute("INSERT INTO #{qt(fts_table_name(model))}(#{qt(fts_table_name(model))}) VALUES('optimize');")
+        FullSearch::Instrumentation.instrument("optimize", model: model.name) do
+          sqlite!(model)
+          connection.execute("INSERT INTO #{qt(fts_table_name(model))}(#{qt(fts_table_name(model))}) VALUES('optimize');")
+        end
       end
 
       def reindex_source_fields!(model)
         dsl = model.full_search_dsl
         return unless dsl
 
-        model.find_each do |record|
-          dsl.fields.each do |field|
-            FullSearch::Callbacks.reindex_field!(record, field.name) if field.source
-          end
+        source_fields = dsl.fields.select(&:source)
+        return if source_fields.empty?
+
+        model.find_each(batch_size: 500) do |record|
+          pairs = source_fields.to_h { |f| [column_name(f), FullSearch::Model.evaluate_source(record, f).to_s] }
+          next if pairs.empty?
+          upsert_source_row!(model, record.id, pairs)
         end
       end
 
+      def upsert_source_row!(model, rowid, values)
+        table = qt(fts_table_name(model))
+        sets = values.map { |name, value| "#{qc(name)} = #{q(value)}" }.join(", ")
+
+        connection.execute(<<~SQL)
+          UPDATE #{table} SET #{sets} WHERE rowid = #{q(rowid)};
+        SQL
+      end
+
       def create_triggers!(model)
         connection.execute(insert_trigger_sql(model))
         connection.execute(delete_trigger_sql(model))
@@ -137,6 +155,7 @@ module FullSearch
       end
 
       def drop!(model)
+        IndexCache.clear!
         verified_tables.delete(model.table_name)
         sqlite!(model)
         drop_triggers!(model)
@@ -168,10 +187,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 +228,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!
@@ -494,15 +517,13 @@ module FullSearch
       # For multi-process or multi-host deployments, run full_search:rebuild from a single
       # deployment step. See README.
       def with_rebuild_lock(model)
-        if FullSearch.config.lock_rebuilds
-          connection.transaction do
+        connection.transaction do
+          if FullSearch.config.lock_rebuilds
             connection.execute(
-              "INSERT INTO full_search_index_versions (table_name, config_hash, rebuilt_at) VALUES (#{q(model.table_name)}, #{q("__rebuilding__")}, datetime('now'))
+              "INSERT INTO full_search_index_versions (table_name, config_hash, rebuilt_at) VALUES (#{q(model.table_name)}, #{q(FullSearch::Constants::REBUILDING_HASH)}, datetime('now'))
                ON CONFLICT(table_name) DO UPDATE SET config_hash=excluded.config_hash;"
             )
-            yield
           end
-        else
           yield
         end
       end

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/instrumentation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FullSearch
+  module Instrumentation
+    def self.instrument(name, payload = {}, &block)
+      ActiveSupport::Notifications.instrument("full_search.#{name}", payload, &block)
+    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,43 +15,48 @@ 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
+    MIN_TERM_LENGTH = FullSearch::Constants::MIN_TERM_LENGTH
 
     def relation
-      validate_filter_keys!
-      validate_required_filters!
-      check_stale_config!
-
-      return model.none if dsl.tokenize == "trigram" && query.length < MIN_TERM_LENGTH && !dsl.typo_tolerance?
-
-      parsed = QueryParser.parse(query)
-      exact_ids = ExactMatch.ids_for(model, query, filters)
-      primary_ids = fts_match_ids(parsed)
-      fallback_ids = (dsl.typo_tolerance? && matching_strategy != "all") ? trigram_match_ids(parsed, primary_ids, candidate_limit: per_strategy_limit) : []
-      fuzzy_ids = (dsl.typo_tolerance? && matching_strategy != "all" && primary_ids.empty? && fallback_ids.empty?) ? fuzzy_match_ids(parsed, candidate_limit: per_strategy_limit) : []
-
-      all_ids = (exact_ids + primary_ids + fallback_ids + fuzzy_ids).uniq
-      return model.none if all_ids.empty?
-
-      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 = rel.limit(limit) if limit
-      rel = rel.offset(offset) if offset
-
-      rel = apply_ranking(rel, all_ids, exact_ids)
-
-      if highlight
-        records = rel.to_a
-        Highlighter.apply!(records, model, query, record_ids: records.map(&:id))
-        records
-      elsif highlight_fields
-        records = rel.to_a
-        Highlighter.apply_fields!(records, model, query, record_ids: records.map(&:id))
-        records
-      else
-        rel
+      FullSearch::Instrumentation.instrument("query", model: model.name, query: query) do
+        validate_filter_keys!
+        validate_required_filters!
+        check_stale_config!
+
+        return model.none if dsl.tokenize == "trigram" && query.length < MIN_TERM_LENGTH && !dsl.typo_tolerance?
+
+        parsed = QueryParser.parse(query)
+        exact_ids = ExactMatch.ids_for(model, query, filters)
+        primary_ids = fts_match_ids(parsed)
+        fallback_ids = (dsl.typo_tolerance? && matching_strategy != "all") ? trigram_match_ids(parsed, primary_ids, candidate_limit: per_strategy_limit) : []
+        fuzzy_ids = (dsl.typo_tolerance? && matching_strategy != "all" && primary_ids.empty? && fallback_ids.empty?) ? fuzzy_match_ids(parsed, candidate_limit: per_strategy_limit) : []
+
+        all_ids = (exact_ids + primary_ids + fallback_ids + fuzzy_ids).uniq
+        return model.none if all_ids.empty?
+
+        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 = rel.includes(includes) if includes
+
+        if highlight
+          records = rel.to_a
+          Highlighter.apply!(records, model, query, record_ids: records.map(&:id))
+          records
+        elsif highlight_fields
+          records = rel.to_a
+          Highlighter.apply_fields!(records, model, query, record_ids: records.map(&:id))
+          records
+        else
+          rel
+        end
       end
     end
 
@@ -84,7 +89,7 @@ module FullSearch
 
       stored = begin
         FullSearch::Index.stored_config_hash(model)
-      rescue StandardError
+      rescue
         nil
       end
       return unless stored
@@ -137,6 +142,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 +168,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)
@@ -273,7 +281,7 @@ module FullSearch
     def max_allowed_typos(length)
       min_length = dsl.typo_tolerance_min_term_length.to_i
       return -1 if length < min_length
-      return 2 if length >= 9
+      return 2 if length >= FullSearch::Constants::TWO_TYPO_MIN_LENGTH
       1
     end
 
@@ -299,7 +307,8 @@ module FullSearch
       tbl = qt(model.table_name)
 
       if exact_ids.any?
-        order_parts << "CASE #{tbl}.id #{exact_ids.map { |id| "WHEN #{q(id)} THEN 0" }.join(" ")} ELSE 1 END"
+        boost_ids = exact_ids.first(FullSearch::Constants::MAX_EXACT_MATCH_BOOST_IDS)
+        order_parts << "CASE #{tbl}.id #{boost_ids.map { |id| "WHEN #{q(id)} THEN 0" }.join(" ")} ELSE 1 END"
       end
 
       fts_table = qt(FullSearch::Index.fts_table_name(model))

data/lib/full_search/version.rb

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

data/lib/full_search.rb

@@ -4,6 +4,9 @@ require "active_record"
 require "active_support"
 require "active_support/concern"
 
+require "full_search/constants"
+require "full_search/index_cache"
+require "full_search/instrumentation"
 require "full_search/version"
 require "full_search/config"
 require "full_search/distance"
@@ -38,6 +41,10 @@ module FullSearch
       @models ||= Set.new
     end
 
+    def sorted_models
+      models.sort_by { |m| m.table_name.to_s }
+    end
+
     def register_model(model)
       models << model
     end
@@ -47,11 +54,11 @@ module FullSearch
     end
 
     def optimize!
-      models.each { |model| Index.optimize!(model) }
+      sorted_models.each { |model| Index.optimize!(model) }
     end
 
     def setup!
-      models.each do |model|
+      sorted_models.each do |model|
         Index.ensure_table!(model)
         Callbacks.install!(model)
       end

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

data/lib/tasks/full_search.rake

@@ -12,7 +12,7 @@ def resolve_full_search_models(args)
       klass || FullSearch.models.find { |m| m.table_name == name }
     end.compact
   else
-    FullSearch.models
+    FullSearch.sorted_models
   end
 end
 
@@ -31,7 +31,7 @@ namespace :full_search do
         klass
       end.compact
     else
-      FullSearch.models
+      FullSearch.sorted_models
     end
 
     FullSearch.setup!
@@ -77,7 +77,7 @@ namespace :full_search do
   task optimize: :environment do
     Rails.application.eager_load!
     FullSearch.optimize!
-    FullSearch.models.each do |model|
+    FullSearch.sorted_models.each do |model|
       puts "Optimized #{FullSearch::Index.fts_table_name(model)}"
     end
   end
@@ -85,7 +85,7 @@ namespace :full_search do
   desc "Show full_search index status"
   task status: :environment do
     Rails.application.eager_load!
-    FullSearch.models.each do |model|
+    FullSearch.sorted_models.each do |model|
       stored = FullSearch::Index.stored_config_hash(model)
       current = model.full_search_dsl.config_hash
       status = (stored == current) ? "ok" : "stale"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: full_search
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.8
 platform: ruby
 authors:
 - Ben D'Angelo
@@ -144,12 +144,15 @@ files:
 - lib/full_search/bulk_import.rb
 - lib/full_search/callbacks.rb
 - lib/full_search/config.rb
+- lib/full_search/constants.rb
 - lib/full_search/distance.rb
 - lib/full_search/dsl.rb
 - lib/full_search/errors.rb
 - 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/instrumentation.rb
 - lib/full_search/model.rb
 - lib/full_search/multi_search.rb
 - lib/full_search/optimize_job.rb