full_search 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 339422f4765fd1cd96ef55e9d026d782e10b08c2c6d1636d6e2e13454cf12b51
-  data.tar.gz: fc5b3a6105d9359162aebb6d14dddf6763e0e0e301351157a1c1c278386d3355
+  metadata.gz: 50bb1c53fe9f326612a2413a441a37acfe48f25bf4730786de3631c7230b2572
+  data.tar.gz: ab53bbd57f8fd9cb464af29d37aa70cd0efb18a2835eff1b501d61a14d0de43f
 SHA512:
-  metadata.gz: 38a981537301ec24ec8ee6d38d1174e771b5dbdb3ebc4fa3e0bea857c60d3a440156e5cf9b1ae43be068c616f65381f4866d6294aa9aa4dab5a3e662cb3bfe44
-  data.tar.gz: 1c1af3ef0948200256f76013f66da00e1764379dbbc07ac8d90264e1a55b9e416218e8569675179736b59821b288aa9ce6fe24fccea48079f60847f127129451
+  metadata.gz: ab98601c786c02808246cf4657ef7c3912e36e0fbc429417c0ff564a3ec1e2575216fda8d64ee2ab22db32c707bcbce0915fcc3d57038059f1dfe05bde48963e
+  data.tar.gz: 52564a1ce083d5aa0f6cb624f8f9aa4a0bb0ac13a85216f14a857a5c2c2c744d37fa4370272679c3bd13c76eb6ec732814463cfa143bb714654243968c6c800c

data/README.md

@@ -1,10 +1,18 @@
 # full_search
 
+[![CI](https://github.com/bendangelo/full_search/actions/workflows/ci.yml/badge.svg)](https://github.com/bendangelo/full_search/actions/workflows/ci.yml)
+
 SQLite FTS5 full-text search for Rails/ActiveRecord. A lightweight, self-contained alternative to `pg_search` for apps already running on SQLite.
 
+## Requirements
+
+- Ruby 3.1+
+- Rails 8.0+
+- SQLite 3.34+ (if using typo tolerance)
+
 ## When to use
 
-`full_search` is designed for apps with **100,000 records or fewer per table** that want full-text search without running a separate service. If you're on SQLite and need keyword search, phrase matching, typo-tolerant substring queries, or result highlighting, this gem gives you production-quality search with zero infrastructure — no Elasticsearch, no Meilisearch, no Sidekiq queue.
+`full_search` is designed for apps with **100,000 records or fewer per table** that want full-text search without running a separate service. If you're on SQLite and need keyword search, phrase matching, typo-tolerant substring queries, or result highlighting, this gem gives you full-text search suitable for small to medium SQLite-backed apps with zero infrastructure — no Elasticsearch, no Meilisearch, no Sidekiq queue.
 
 ## Installation
 
@@ -70,6 +78,10 @@ These two operations are often confused:
 - **Rebuild** (`full_search:rebuild` / `Customer.rebuild!`) — drops and recreates the FTS virtual table. Needed when the DSL changes (fields added/removed, tokenizer changed, etc.). The table is re-created from scratch, backfilled, triggers re-installed, and the index is optimized.
 - **Reindex** (`Customer.reindex!` / `FullSearch::Index.reindex_source_fields!`) — updates existing FTS rows with fresh values from computed `source:` fields only. The table structure is untouched. Database triggers cover regular column changes automatically; only Ruby-evaluated `source:` blocks need an explicit reindex.
 
+> **Note on rebuild locking:** The `lock_rebuilds` option prevents concurrent rebuilds
+> within the same process/connection. For multi-process or multi-host deployments,
+> run `full_search:rebuild` from a single deployment step.
+
 ### Auto-rebuild on app load
 
 When `auto_rebuild_schema` is enabled (default in the generated initializer), the railtie hooks into Rails `after_initialize` and:
@@ -132,7 +144,7 @@ If you're not on Solid Queue, most job frameworks support recurring schedules vi
 
 ### Config hash drift detection
 
-Every FTS table stores a SHA256 digest of its DSL configuration in the `full_search_index_versions` table. When the DSL changes (e.g., adding a field), the stored hash no longer matches, and `rebuild!` is triggered automatically (if `auto_rebuild_schema` is true) to bring the index in line with the new definition. If `auto_rebuild_schema` is false, queries still run but raise `ConfigChangedError` when the hash doesn't match.
+Every FTS table stores a SHA256 digest of its DSL configuration in the `full_search_index_versions` table. When the DSL changes (e.g., adding a field), the stored hash no longer matches, and `rebuild!` is triggered automatically (if `auto_rebuild_schema` is true) to bring the index in line with the new definition. If `auto_rebuild_schema` is false, queries raise `ConfigChangedError` when the hash doesn't match (or log a warning and fall back if configured with `:log_and_fallback`).
 
 ## Query operators
 
@@ -169,9 +181,15 @@ class Customer < ApplicationRecord
 end
 ```
 
-`typo_tolerance` uses an FTS5 trigram shadow table as a fallback when the primary index returns no results. It is substring matching, not edit-distance correction, and requires SQLite >= 3.34.
+`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.
 
 ## 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.
-- Per-model only; no built-in multi-model aggregator
+- Per-model only; `multi_search` returns grouped results, not a unified ranked list
+- No built-in multi-model aggregator
+
+## Security
+
+If you discover a security vulnerability, please email the maintainer directly at
+the address listed in the gemspec. Do not file a public issue.

data/lib/full_search/callbacks.rb

@@ -3,6 +3,8 @@
 module FullSearch
   module Callbacks
     def self.install!(model)
+      return if model.instance_variable_get(:@__full_search_callbacks_installed)
+
       dsl = model.full_search_dsl
 
       source_fields = dsl.fields.select(&:source)
@@ -27,6 +29,12 @@ module FullSearch
           FullSearch::Callbacks.reindex_dependents!(record, model, field)
         end
       end
+
+      model.instance_variable_set(:@__full_search_callbacks_installed, true)
+    end
+
+    def self.reset_installed_flag!(model)
+      model.instance_variable_set(:@__full_search_callbacks_installed, false)
     end
 
     def self.reindex_record!(record)
@@ -46,22 +54,24 @@ module FullSearch
       return unless field&.source
 
       value = record.instance_exec(&field.source)
-      table = FullSearch::Index.fts_table_name(record.class)
-      quoted_value = ActiveRecord::Base.connection.quote(value.to_s)
-      ActiveRecord::Base.connection.execute(
-        "UPDATE #{table} SET #{field.name} = #{quoted_value} WHERE rowid = #{record.id}"
+      table = qt(FullSearch::Index.fts_table_name(record.class))
+      conn = ActiveRecord::Base.connection
+      conn.execute(
+        "UPDATE #{table} SET #{qc(field.name)} = #{q(value.to_s)} WHERE rowid = #{q(record.id)}"
       )
     end
 
     def self.remove_record!(record)
-      table = FullSearch::Index.fts_table_name(record.class)
-      ActiveRecord::Base.connection.execute("DELETE FROM #{table} WHERE rowid = #{record.id}")
+      table = qt(FullSearch::Index.fts_table_name(record.class))
+      conn = ActiveRecord::Base.connection
+      conn.execute("DELETE FROM #{table} WHERE rowid = #{q(record.id)}")
     end
 
     def self.reindex_dependents!(parent_record, dependent_model, field)
       fk = association_key(dependent_model, field.reindex_on)
-      sql = "SELECT id FROM #{dependent_model.table_name} WHERE #{fk} = #{parent_record.id}"
-      dependent_ids = ActiveRecord::Base.connection.execute(sql).map { |r| r["id"] }
+      conn = ActiveRecord::Base.connection
+      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
@@ -73,6 +83,14 @@ module FullSearch
       end
     end
 
+    class << self
+      include FullSearch::Quoting
+    end
+
+    def self.connection
+      ActiveRecord::Base.connection
+    end
+
     def self.associated_class(model, association_name)
       reflection = model.reflect_on_association(association_name.to_sym)
       reflection&.klass

data/lib/full_search/config.rb

@@ -11,7 +11,6 @@ module FullSearch
       @default_async_reindex = true
       @default_tokenizer = "unicode61"
     end
-
   end
 
   class << self

data/lib/full_search/distance.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FullSearch
+  module Distance
+    def self.damerau_levenshtein(a, b)
+      a_len = a.length
+      b_len = b.length
+      return a_len if b_len == 0
+      return b_len if a_len == 0
+
+      d = Array.new(a_len + 1) { Array.new(b_len + 1, 0) }
+      (0..a_len).each { |i| d[i][0] = i }
+      (0..b_len).each { |j| d[0][j] = j }
+
+      (1..a_len).each do |i|
+        (1..b_len).each do |j|
+          cost = (a[i - 1] == b[j - 1]) ? 0 : 1
+          d[i][j] = [
+            d[i - 1][j] + 1,
+            d[i][j - 1] + 1,
+            d[i - 1][j - 1] + cost
+          ].min
+
+          if i > 1 && j > 1 && a[i - 1] == b[j - 2] && a[i - 2] == b[j - 1]
+            d[i][j] = [d[i][j], d[i - 2][j - 2] + 1].min
+          end
+        end
+      end
+
+      d[a_len][b_len]
+    end
+  end
+end

data/lib/full_search/dsl.rb

@@ -2,10 +2,10 @@
 
 module FullSearch
   class Dsl
-    attr_reader :fields, :exact_matches, :filters, :model_class, :tokenize, :highlight_config, :rank_bys
+    attr_reader :fields, :exact_matches, :filters, :model_class, :highlight_config, :rank_bys
 
-    Field = Data.define(:name, :weight, :source, :reindex_on, :async, :as)
-    ExactMatch = Data.define(:name, :source)
+    Field = Data.define(:name, :weight, :source, :reindex_on, :async, :as, :version)
+    ExactMatch = Data.define(:name, :source, :version)
     Filter = Data.define(:name, :required)
     RankBy = Data.define(:column, :direction)
 
@@ -19,35 +19,49 @@ module FullSearch
       @soft_delete_column = nil
     end
 
-    def field(name, weight: 1, source: nil, reindex_on: nil, async: FullSearch.config.default_async_reindex, as: nil)
+    def field(name, weight: 1, source: nil, reindex_on: nil, async: FullSearch.config.default_async_reindex, as: nil, version: nil)
       unless valid_name?(name)
         raise InvalidFieldError, "Invalid field name: #{name.inspect}"
       end
       if as && !valid_name?(as)
         raise InvalidFieldError, "Invalid field alias (as): #{as.inspect}"
       end
-      @fields << Field.new(name: name.to_s, weight: weight.to_i, source: source, reindex_on: reindex_on&.to_s, async: async, as: as&.to_s)
+      str = name.to_s
+      raise InvalidFieldError, "Duplicate field name: #{name.inspect}" if fields.any? { |f| f.name == str }
+      raise InvalidFieldError, "Field name conflicts with filter: #{name.inspect}" if filters.any? { |f| f.name == str }
+      @fields << Field.new(name: str, weight: weight.to_i, source: source, reindex_on: reindex_on&.to_s, async: async, as: as&.to_s, version: version)
     end
 
-    def exact_match(name, source: -> { public_send(name) })
+    def exact_match(name, source: -> { public_send(name) }, version: nil)
       unless valid_name?(name)
         raise InvalidFieldError, "Invalid exact_match name: #{name.inspect}"
       end
-      @exact_matches << ExactMatch.new(name: name.to_s, source: source)
+      str = name.to_s
+      raise InvalidFieldError, "Duplicate exact_match name: #{name.inspect}" if exact_matches.any? { |e| e.name == str }
+      @exact_matches << ExactMatch.new(name: str, source: source, version: version)
     end
 
     def rank_by(column, direction = :desc)
       unless valid_name?(column)
         raise InvalidFieldError, "Invalid rank_by column: #{column.inspect}"
       end
-      @rank_bys << RankBy.new(column: column.to_s, direction: direction.to_sym)
+      dir = direction.to_s.downcase
+      unless %w[asc desc].include?(dir)
+        raise InvalidFieldError, "Invalid rank_by direction: #{direction.inspect}. Use :asc or :desc."
+      end
+      str = column.to_s
+      raise InvalidFieldError, "Duplicate rank_by column: #{column.inspect}" if rank_bys.any? { |r| r.column == str }
+      @rank_bys << RankBy.new(column: str, direction: dir.to_sym)
     end
 
     def filter(name, required: false)
       unless valid_name?(name)
         raise InvalidFieldError, "Invalid filter name: #{name.inspect}"
       end
-      @filters << Filter.new(name: name.to_s, required: required)
+      str = name.to_s
+      raise InvalidFieldError, "Duplicate filter name: #{name.inspect}" if filters.any? { |f| f.name == str }
+      raise InvalidFieldError, "Filter name conflicts with field: #{name.inspect}" if fields.any? { |f| f.name == str }
+      @filters << Filter.new(name: str, required: required)
     end
 
     def soft_delete_column(name = :_no_arg_)
@@ -67,7 +81,7 @@ module FullSearch
     end
 
     def highlight(open_tag: "<mark>", close_tag: "</mark>")
-      @highlight_config = { open_tag: open_tag, close_tag: close_tag }
+      @highlight_config = {open_tag: open_tag, close_tag: close_tag}
     end
 
     def typo_tolerance(enabled = true, min_term_length: nil)
@@ -91,8 +105,8 @@ module FullSearch
         soft_delete_column,
         typo_tolerance?,
         typo_tolerance_min_term_length,
-        fields.map { |f| [f.name, f.weight, f.source.nil? ? "column" : f.source.source_location&.join(":"), f.reindex_on, f.async, f.as] },
-        exact_matches.map { |e| [e.name, e.source&.source_location&.join(":")] },
+        fields.map { |f| [f.name, f.weight, f.source.nil? ? "column" : "proc:#{f.version}", f.reindex_on, f.async, f.as] },
+        exact_matches.map { |e| [e.name, "proc:#{e.version}"] },
         filters.map { |f| [f.name, f.required] },
         rank_bys.map { |r| [r.column, r.direction] }
       ].inspect)

data/lib/full_search/errors.rb

@@ -3,8 +3,10 @@
 module FullSearch
   class Error < StandardError; end
   class MissingRequiredFilterError < Error; end
+  class UnknownFilterError < Error; end
   class ConfigChangedError < Error; end
   class InvalidFieldError < Error; end
   class NotConfiguredError < Error; end
   class UnsupportedDatabaseError < Error; end
+  class InvalidQueryError < Error; end
 end

data/lib/full_search/exact_match.rb

@@ -12,20 +12,14 @@ module FullSearch
       relation = model.all
       filters.each { |name, value| relation = relation.where(name => value) }
 
-      exact_ids = dsl.exact_matches.flat_map do |em|
-        value = exact_match_value(em, cleaned)
-        next [] if value.nil? || value.to_s.empty?
-
-        relation.where(em.name => value).pluck(:id)
+      ids = []
+      relation.find_each do |record|
+        dsl.exact_matches.each do |em|
+          value = record.instance_exec(&em.source)
+          ids << record.id if value.to_s.casecmp?(cleaned)
+        end
       end
-
-      exact_ids.uniq
-    end
-
-    def self.exact_match_value(em, query)
-      fake = Object.new
-      fake.define_singleton_method(em.name) { query }
-      fake.instance_exec(&em.source)
+      ids.uniq
     end
   end
 end

data/lib/full_search/highlighter.rb

@@ -2,143 +2,207 @@
 
 module FullSearch
   class Highlighter
-    def self.apply!(records, model, query)
-      snippets = build_snippets(model, query)
-      if snippets.values.all?(&:nil?) && records.any?
-        snippets = manual_snippets(records, model, query)
+    class << self
+      def apply!(records, model, query)
+        snippets = build_snippets(model, query)
+        if snippets.values.all?(&:nil?) && records.any?
+          snippets = manual_snippets(records, model, query)
+        end
+        records.each { |record| record.full_search_snippet = snippets[record.id] }
+        records
       end
-      records.each { |record| record.full_search_snippet = snippets[record.id] }
-      records
-    end
 
-    def self.apply_fields!(records, model, query)
-      fields = build_field_snippets(model, query)
-      if fields.empty? && records.any?
-        fields = manual_field_snippets(records, model, query)
-      end
-      exact_fields = exact_match_field_snippets(records, model, query)
-      records.each do |record|
-        merged = fields[record.id] || {}
-        exact_fields.fetch(record.id, {}).each { |k, v| merged[k] ||= v }
-        record.full_search_highlight_fields = merged
+      def apply_fields!(records, model, query)
+        fields = build_field_snippets(model, query)
+        if fields.values.all?(&:empty?) && records.any?
+          fields = manual_field_snippets(records, model, query)
+        end
+        exact_fields = exact_match_field_snippets(records, model, query)
+        records.each do |record|
+          merged = fields[record.id] || {}
+          exact_fields.fetch(record.id, {}).each { |k, v| merged[k] ||= v }
+          record.full_search_highlight_fields = merged
+        end
+        records
       end
-      records
-    end
 
-    private
+      private
 
-    def self.build_snippets(model, query)
-      rows = highlight_rows(model, query)
-      cols = model.full_search_dsl.fields.map(&:name)
+      def build_snippets(model, query)
+        rows = highlight_rows(model, query)
+        cols = model.full_search_dsl.fields.map(&:name)
 
-      rows.to_h do |row|
-        text = cols.map { |col| row["#{col}_snippet"] }.compact.join(" ").strip
-        [row["rowid"], text.presence]
+        rows.to_h do |row|
+          text = cols.map { |col| row["#{col}_snippet"] }.compact.join(" ").strip
+          [row["rowid"], text.presence]
+        end
       end
-    end
 
-    def self.build_field_snippets(model, query)
-      rows = highlight_rows(model, query)
-      dsl = model.full_search_dsl
-      fields = dsl.fields
-      open_tag = (dsl.highlight_config || { open_tag: "<mark>" })[:open_tag]
-
-      rows.to_h do |row|
-        snippets = fields.each_with_object({}) do |field, hash|
-          snippet = row["#{field.name}_snippet"].to_s.strip
-          key = field.as || field.name
-          hash[key] = snippet if snippet.include?(open_tag)
+      def build_field_snippets(model, query)
+        rows = highlight_rows(model, query)
+        dsl = model.full_search_dsl
+        fields = dsl.fields
+        open_tag = (dsl.highlight_config || {open_tag: "<mark>"})[:open_tag]
+
+        rows.to_h do |row|
+          snippets = fields.each_with_object({}) do |field, hash|
+            snippet = row["#{field.name}_snippet"].to_s.strip
+            key = field.as || field.name
+            hash[key] = snippet if snippet.include?(open_tag)
+          end
+          [row["rowid"], snippets]
         end
-        [row["rowid"], snippets]
       end
-    end
 
-    def self.manual_snippets(records, model, query)
-      dsl = model.full_search_dsl
-      config = dsl.highlight_config || { open_tag: "<mark>", close_tag: "</mark>" }
+      def compute_max_typos(query, dsl)
+        return nil unless dsl.typo_tolerance?
+        length = query.length
+        min_length = dsl.typo_tolerance_min_term_length.to_i
+        return nil if length < min_length
+        return 2 if length >= 9
+        1
+      end
+
+      def manual_snippets(records, model, query)
+        dsl = model.full_search_dsl
+        config = dsl.highlight_config || {open_tag: "<mark>", close_tag: "</mark>"}
         cols = dsl.fields.map(&:name)
+        max_typos = compute_max_typos(query, dsl)
 
         records.to_h do |record|
           text = cols.map { |col| record.full_search_text_for(col).to_s }.join(" ").strip
-          highlighted = manual_highlight(text, query, config)
+          highlighted = manual_highlight(text, query, config, max_typos: max_typos)
           [record.id, highlighted.presence]
         end
-    end
+      end
+
+      def manual_field_snippets(records, model, query)
+        dsl = model.full_search_dsl
+        config = dsl.highlight_config || {open_tag: "<mark>", close_tag: "</mark>"}
+        fields = dsl.fields
+        max_typos = compute_max_typos(query, dsl)
 
-    def self.manual_field_snippets(records, model, query)
-      dsl = model.full_search_dsl
-      config = dsl.highlight_config || { open_tag: "<mark>", close_tag: "</mark>" }
-      fields = dsl.fields
-
-      records.to_h do |record|
-        snippets = fields.each_with_object({}) do |field, hash|
-          value = record.full_search_text_for(field.name).to_s
-          highlighted = manual_highlight(value, query, config)
-          key = field.as || field.name
-          hash[key] = highlighted if highlighted.include?(config[:open_tag])
+        records.to_h do |record|
+          snippets = fields.each_with_object({}) do |field, hash|
+            value = record.full_search_text_for(field.name).to_s
+            highlighted = manual_highlight(value, query, config, max_typos: max_typos)
+            key = field.as || field.name
+            hash[key] = highlighted if highlighted.include?(config[:open_tag])
+          end
+          [record.id, snippets]
         end
-        [record.id, snippets]
       end
-    end
 
-    def self.exact_match_field_snippets(records, model, query)
-      dsl = model.full_search_dsl
-      return {} if dsl.exact_matches.empty?
+      def exact_match_field_snippets(records, model, query)
+        dsl = model.full_search_dsl
+        return {} if dsl.exact_matches.empty?
 
-      config = dsl.highlight_config || { open_tag: "<mark>", close_tag: "</mark>" }
+        config = dsl.highlight_config || {open_tag: "<mark>", close_tag: "</mark>"}
+        max_typos = compute_max_typos(query, dsl)
 
-      records.to_h do |record|
-        snippets = dsl.exact_matches.each_with_object({}) do |em, hash|
-          value = exact_match_field_value(em, record)
-          highlighted = manual_highlight(value.to_s, query, config)
-          hash[em.name.to_s] = highlighted if highlighted.include?(config[:open_tag])
+        records.to_h do |record|
+          snippets = dsl.exact_matches.each_with_object({}) do |em, hash|
+            value = exact_match_field_value(em, record)
+            highlighted = manual_highlight(value.to_s, query, config, max_typos: max_typos)
+            hash[em.name.to_s] = highlighted if highlighted.include?(config[:open_tag])
+          end
+          [record.id, snippets]
         end
-        [record.id, snippets]
       end
-    end
 
-    def self.exact_match_field_value(em, record)
-      if em.source
-        record.instance_exec(&em.source)
-      else
-        record.public_send(em.name)
+      def exact_match_field_value(em, record)
+        if em.source
+          record.instance_exec(&em.source)
+        else
+          record.public_send(em.name)
+        end
       end
-    end
 
-    def self.manual_highlight(text, query, config)
-      return text if text.empty? || query.empty?
-      text.gsub(/#{Regexp.escape(query)}/i, "#{config[:open_tag]}\\0#{config[:close_tag]}")
-    end
+      def manual_highlight(text, query, config, max_typos: nil)
+        return text if text.empty? || query.empty?
+
+        open_tag = config[:open_tag]
+        close_tag = config[:close_tag]
+        escaped_query = Regexp.escape(query)
 
-    def self.highlight_rows(model, query)
-      dsl = model.full_search_dsl
-      config = dsl.highlight_config || { open_tag: "<mark>", close_tag: "</mark>" }
-      match_expr = QueryParser.to_match_expression(QueryParser.parse(query))
-      return [] if match_expr.empty?
+        if text.match?(/#{escaped_query}/i)
+          return text.gsub(/#{escaped_query}/i, "#{open_tag}\\0#{close_tag}")
+        end
+
+        best = best_fuzzy_match(text, query, max_typos: max_typos)
+        if best
+          start_pos, end_pos = best
+          return "#{text[0...start_pos]}#{open_tag}#{text[start_pos...end_pos]}#{close_tag}#{text[end_pos..]}"
+        end
 
-      table = FullSearch::Index.fts_table_name(model)
-      cols = dsl.fields.map(&:name)
-      return [] if cols.empty?
+        text
+      end
 
-      highlight_parts = cols.each_with_index.map do |col, idx|
-        "highlight(#{table}, #{idx}, #{quote(config[:open_tag])}, #{quote(config[:close_tag])}) AS #{col}_snippet"
-      end.join(", ")
+      def best_fuzzy_match(text, query, max_typos: nil)
+        query_len = query.length
+        text_len = text.length
+        return nil if query_len == 0 || text_len == 0
 
-      sql = <<~SQL
-        SELECT rowid, #{highlight_parts}
-        FROM #{table}
-        WHERE #{table} MATCH #{quote(match_expr)}
-      SQL
+        max_typos ||= max_allowed_typos(query_len)
+        return nil if max_typos < 0
 
-      connection.execute(sql)
-    end
+        best_score = max_typos + 1
+        best_range = nil
 
-    def self.connection
-      ActiveRecord::Base.connection
-    end
+        min_window = [1, query_len - max_typos].max
+        max_window = [text_len, query_len + max_typos].min
+        return nil if min_window > max_window
+
+        (min_window..max_window).each do |window_len|
+          (0..(text_len - window_len)).each do |start|
+            substr = text[start, window_len]
+            distance = Distance.damerau_levenshtein(query.downcase, substr.downcase)
+            next if distance > max_typos
+
+            if best_range.nil? || distance < best_score || (distance == best_score && window_len > (best_range[1] - best_range[0]))
+              best_score = distance
+              best_range = [start, start + window_len]
+            end
+          end
+        end
+
+        best_range
+      end
 
-    def self.quote(value)
-      connection.quote(value)
+      def max_allowed_typos(length)
+        return -1 if length < 3
+        return 2 if length >= 9
+        1
+      end
+
+      def highlight_rows(model, query)
+        dsl = model.full_search_dsl
+        config = dsl.highlight_config || {open_tag: "<mark>", close_tag: "</mark>"}
+        match_expr = QueryParser.to_match_expression(QueryParser.parse(query))
+        return [] if match_expr.empty?
+
+        table = qt(FullSearch::Index.fts_table_name(model))
+        cols = dsl.fields.map(&:name)
+        return [] if cols.empty?
+
+        highlight_parts = cols.each_with_index.map do |col, idx|
+          "highlight(#{table}, #{idx}, #{q(config[:open_tag])}, #{q(config[:close_tag])}) AS #{qc("#{col}_snippet")}"
+        end.join(", ")
+
+        sql = <<~SQL
+          SELECT rowid, #{highlight_parts}
+          FROM #{table}
+          WHERE #{table} MATCH #{q(match_expr)}
+        SQL
+
+        connection.execute(sql)
+      end
+
+      include Quoting
+
+      def connection
+        ActiveRecord::Base.connection
+      end
     end
   end
 end