full_search 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b466311e2305f90987a48ff58cee59f4c81af6e960b5fcd2fe09cf845b985b
-  data.tar.gz: 1d355e22aa06d280d984d7da1df90e57a8ca4a5f5676b7870424f2b048c051ba
+  metadata.gz: d25d24145bf1aef1508210eb9d6879b21218ed8760ef6a61812706720a12ac17
+  data.tar.gz: 94b71b2b86db367ef8fde640550ab7b5945b50829d618c5e4eb41a4d9a6e0d65
 SHA512:
-  metadata.gz: 9489ff8c9bf04c59b6380cd1810871a39a947421754379ac6fb1c1cb36cbf7850a753d0a7354e25f38b591aeae63cbb05cd7d8c0f187bb84ba6ef191aba19755
-  data.tar.gz: a23ce1270f3ac088b02774a43178fb277811e7df65a7d518f3fde4b8899cfb2db3f07164c72ea75ec26bb3b8ed9ef29b94d05aa53009ef1f82dd9d1bb4d14f79
+  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:
@@ -125,6 +160,22 @@ These two operations are often confused:
 > within the same process/connection. For multi-process or multi-host deployments,
 > run `full_search:rebuild` from a single deployment step.
 
+### First-deploy setup
+
+After `db:prepare` creates your application tables, FTS virtual tables like `customers_fts` do not yet exist. Run `full_search:prepare` to create them:
+
+```bash
+bin/rails full_search:prepare
+```
+
+For Docker-based deployments, add this to your entrypoint script after `db:prepare:with_data`:
+
+```bash
+./bin/rails full_search:prepare
+```
+
+The `full_search:prepare` task is idempotent — it only creates missing tables and installs triggers. It will not drop or rebuild existing indexes, making it safe to run on every deploy.
+
 ### Auto-rebuild on app load
 
 When `auto_rebuild_schema` is enabled (default in the generated initializer), the railtie hooks into Rails `after_initialize` and:
@@ -162,6 +213,7 @@ bin/rails full_search:reset
 
 | Task | Description |
 |------|-------------|
+| `full_search:prepare` | Idempotent setup — creates missing FTS tables and triggers without dropping existing ones. Safe to run on every deploy. Add to your Docker entrypoint after `db:prepare:with_data` for first-deploy automation. |
 | `full_search:rebuild` | Drops and recreates the FTS virtual table only when the DSL config hash has changed (safe for production). Pass model names to target specific tables. |
 | `full_search:reset` | Force a full rebuild — drops and recreates all FTS tables regardless of config hash. Use when data may be out of sync. |
 | `full_search:optimize` | Run FTS5 [`optimize`](https://www.sqlite.org/fts5.html#the_optimize_command) to merge b-tree segments. Useful after bulk updates. |
@@ -223,6 +275,17 @@ end
 
 When this option is `true`, the first search that detects a stale index automatically calls `FullSearch::Index.rebuild_if_needed!` and then proceeds with the query, so you don't need to restart the server or run a Rake task during iterative development. In production, this defaults to `false`; use `full_search:rebuild` or boot-time `auto_rebuild_schema` instead.
 
+### Missing table error
+
+When the FTS table does not exist and a search is attempted, `full_search` raises `MissingTableError` with a clear message:
+
+```
+FullSearch::MissingTableError: FTS table `customers_fts` does not exist.
+Run `bin/rails full_search:prepare` to create it.
+```
+
+This mirrors how Rails handles missing database tables — you see the error, run the task, and move on. Add `full_search:prepare` to your deploy pipeline or Docker entrypoint after `db:prepare:with_data` to prevent the error in production.
+
 ## Query operators
 
 ```ruby
@@ -260,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/errors.rb

@@ -8,5 +8,6 @@ module FullSearch
   class InvalidFieldError < Error; end
   class NotConfiguredError < Error; end
   class UnsupportedDatabaseError < Error; end
+  class MissingTableError < Error; end
   class InvalidQueryError < Error; end
 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,16 @@ 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)
+        !table_exists?(model)
       end
 
       private
@@ -203,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
@@ -78,7 +81,15 @@ module FullSearch
     end
 
     def check_stale_config!
-      stored = FullSearch::Index.stored_config_hash(model)
+      if FullSearch::Index.missing_table?(model)
+        raise MissingTableError, "FTS table `#{FullSearch::Index.fts_table_name(model)}` does not exist. Run `bin/rails full_search:prepare` to create it."
+      end
+
+      stored = begin
+        FullSearch::Index.stored_config_hash(model)
+      rescue
+        nil
+      end
       return unless stored
 
       return if stored == dsl.config_hash
@@ -129,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
 
@@ -154,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.5"
+  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

data/lib/tasks/full_search.rake

@@ -17,6 +17,29 @@ def resolve_full_search_models(args)
 end
 
 namespace :full_search do
+  desc "Create full_search FTS tables and triggers if missing (idempotent, safe for first deploy)"
+  task :prepare, [:models] => :environment do |_t, args|
+    Rails.application.eager_load!
+
+    models = if args[:models]
+      args[:models].split(",").map do |name|
+        klass = begin
+          name.singularize.camelize.constantize
+        rescue NameError, LoadError
+          FullSearch.models.find { |m| m.table_name == name }
+        end
+        klass
+      end.compact
+    else
+      FullSearch.models
+    end
+
+    FullSearch.setup!
+    models.each do |model|
+      puts "Prepared #{FullSearch::Index.fts_table_name(model)}"
+    end
+  end
+
   desc "Rebuild indexes when DSL has changed (checks config hash; safe for production)"
   task :rebuild, [:models] => :environment do |_t, args|
     Rails.application.eager_load!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: full_search
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  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