huginn_datatable 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '05719914312baa1225e26059bd5154312ee5df8bc369df6f5f9676d423ed9d0e'
-  data.tar.gz: b876f81b7add7781a4bd6b7424e3674f251c09ecfe38e0a70e8f891bb2286c76
+  metadata.gz: e68c742da97818c79b41681099972a3e4c3cc4613b8500831226abe09b2a87ed
+  data.tar.gz: 855168e5b6bbc9df1bceb381484bf20f550fcf57c0d0a35d6aba15c50b20a775
 SHA512:
-  metadata.gz: bed2c0bc55d70a6ceaa57a6a84fb264360df75cbab4f42a2a82031073fdd0f15778b1681afcdc35aba31a478e4e8c18a6acfc960b725a1018306211845e72c72
-  data.tar.gz: 8f58d9e3fec2d2a38350dc010f9b68d6ab60449e27338291dfae8ae7bcaba2b96cbb64f945067487c1ed97889c6642bbb451dfde21644b0170e708ae109aa30a
+  metadata.gz: f345b93074fec47d95589bdc06078b5c2585a79e0fd2a7c02c519d3ca35baa286a885f94278a64048004891a139f4c97a293848cf094523cbcff85ccc2276ce5
+  data.tar.gz: d2bfa72d92cc096dba420c20e2a9bc0b26f466e0b981b5d9e653d6f5f2dc33c105c5fd12a1c3e3269691ecafd0704efabaec80943f166b610798066420c3fd81

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ### Unreleased
 
+#### 0.3.0
+
+- **New `:full_text` search strategy** — PostgreSQL full text search over lexemes (`public.f_tsvector(col) @@ plainto_tsquery('portuguese'::regconfig, 'term')`), so morphological variants match (e.g. "compras" finds "compra"). Blind to typos, unlike `:pg_trgm`. Uses a GIN tsvector index when the `fts_function` wrapper (IMMUTABLE, dictionary pinned) exists; degrades gracefully to unaccent+ILIKE otherwise.
+- `search_strategy:` now accepts **a single symbol or an Array of them**; multiple strategies are combined with **OR** (a row matches if any strategy matches), e.g. `[ :pg_trgm, :full_text ]` to get typo tolerance plus stemming.
+- New `fts_dictionary:` (default `"portuguese"`) and `fts_function:` (default `"public.f_tsvector"`) configurations, mirroring `unaccent_function`.
+- New generator **`rails g huginn:fts_indexes [Model...]`** scaffolds a migration that creates the IMMUTABLE `public.f_tsvector` wrapper (with `--dictionary`) and GIN tsvector indexes on every `:string`/`:text` column of the Searchable models, including association-scoped ones.
+- `searchable_columns columns: []` is now honored — an empty array means "search only the declared associations", no longer falling back to the model's own string/text columns.
+- Specs for the `Configuration` normalization surface (defaults + `search_strategy` symbol/array shapes).
+
 #### 0.2.1
 
 - Association-scoped `search` now matches through **primary-key semi-join subqueries** (`pk IN (SELECT DISTINCT pk FROM <base> JOIN <chain> WHERE <fuzzy>)`) instead of `left_joins` — one subquery per distinct association chain, combined with OR. The base relation never joins, so the count is a plain `COUNT(*)`.

data/README.md

@@ -66,9 +66,13 @@ gem "huginn"
 ```ruby
 # config/initializers/huginn.rb
 Huginn.configure do |config|
-  # :pg_trgm  (recommended) — trigram similarity (%) OR unaccent+ILIKE
+  # :pg_trgm   (recommended) — trigram similarity (%) OR unaccent+ILIKE
+  # :full_text — PostgreSQL full text search over lexemes
+  #              (to_tsvector @@ plainto_tsquery)
   # :unaccent               — unaccent + ILIKE only
   # :simple                 — plain LIKE
+  # Pass an Array to combine strategies with OR, e.g.
+  # config.search_strategy = [:pg_trgm, :full_text]
   config.search_strategy = :pg_trgm
 
   # Unaccent function used around search terms/columns. Defaults to the pg
@@ -77,6 +81,13 @@ Huginn.configure do |config|
   # indexes can actually be used.
   config.unaccent_function = "unaccent"
 
+  # Full text search (strategy :full_text). The dictionary and the IMMUTABLE
+  # tsvector wrapper (`rails g huginn:fts_indexes`) pinned to that dictionary;
+  # they only apply when the wrapper exists, otherwise search degrades to the
+  # unaccent fallback.
+  # config.fts_dictionary = "portuguese"
+  # config.fts_function   = "public.f_tsvector"
+
   config.pagy_items = 10         # default page size
   config.pagy_max_items = 500    # hard cap for per_page
 end
@@ -84,6 +95,8 @@ end
 
 > **Threshold:** under `:pg_trgm` the similarity cutoff is the PostgreSQL GUC `pg_trgm.similarity_threshold` (default `0.3`), **not** a gem-level setting. Tune it with `SET pg_trgm.similarity_threshold = 0.4` / `SELECT set_limit(0.4)` on the database.
 
+> **Strategy tradeoffs:** `:pg_trgm` tolerates typos and substrings but has no notion of morphology. `:full_text` matches morphological variants (e.g. "correndo"/"correr" → same stem) but is blind to typos, and shines on longer text columns — for name/keyword lookups it mostly overlaps with trigram. Combining both (`[:pg_trgm, :full_text]`) unions the two result sets and requires both index sets (`rails g huginn:trigram_indexes` + `rails g huginn:fts_indexes`).
+
 ## Railtie (automatic include)
 
 By default the Railtie includes `Huginn::Datatable` and `Huginn::Searchable` into every `ActiveRecord::Base` model. You do **not** need `include` statements unless you opt in selectively:

data/README.pt-BR.md

@@ -66,9 +66,13 @@ gem "huginn"
 ```ruby
 # config/initializers/huginn.rb
 Huginn.configure do |config|
-  # :pg_trgm  (recomendado) — similaridade trigram (%) OU unaccent+ILIKE
+  # :pg_trgm   (recomendado) — similaridade trigram (%) OU unaccent+ILIKE
+  # :full_text              — full text search do PostgreSQL sobre lexemas
+  #                           (to_tsvector @@ plainto_tsquery)
   # :unaccent               — somente unaccent + ILIKE
   # :simple                 — LIKE simples
+  # Para combinar estratégias com OR, passe um Array:
+  # config.search_strategy = [:pg_trgm, :full_text]
   config.search_strategy = :pg_trgm
 
   # Função unaccent usada em torno de termos/colunas. O default é o UNACCENT()
@@ -77,6 +81,13 @@ Huginn.configure do |config|
   # GIN trigram possam ser usados de fato.
   config.unaccent_function = "unaccent"
 
+  # Full text search (estratégia :full_text). O dicionário e o wrapper
+  # tsvector IMMUTABLE (`rails g huginn:fts_indexes`) fixado nesse dicionário;
+  # só têm efeito quando o wrapper existe — caso contrário a busca degrada
+  # para o fallback unaccent.
+  # config.fts_dictionary = "portuguese"
+  # config.fts_function   = "public.f_tsvector"
+
   config.pagy_items = 10         # tamanho de página padrão
   config.pagy_max_items = 500    # teto máximo de per_page
 end
@@ -84,6 +95,8 @@ end
 
 > **Limiar:** sob `:pg_trgm`, o corte de similaridade é o GUC do PostgreSQL `pg_trgm.similarity_threshold` (default `0.3`), **não** uma configuração da gem. Ajuste com `SET pg_trgm.similarity_threshold = 0.4` / `SELECT set_limit(0.4)` no banco.
 
+> **Tradeoffs de estratégia:** `:pg_trgm` tolera typos e substrings, mas não tem noção de morfologia. `:full_text` captura variações morfológicas (ex. "correndo"/"correr" → mesmo lexema), mas é cego a typos, e brilha em colunas de texto mais longo — para busca por nome/palavra-chave ele em grande parte se sobrepõe ao trigram. Combinar os dois (`[:pg_trgm, :full_text]`) une os dois conjuntos de resultado e exige os dois conjuntos de índices (`rails g huginn:trigram_indexes` + `rails g huginn:fts_indexes`).
+
 ## Railtie (include automático)
 
 Por padrão, o Railtie inclui `Huginn::Datatable` e `Huginn::Searchable` em toda `ActiveRecord::Base`. Você **não** precisa de `include`, a menos que opte seletivamente:

data/lib/generators/huginn/fts_indexes/fts_indexes_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "generators/huginn/searchable_columns"
+
+module Huginn
+  module Generators
+    # Scaffolds a migration that creates the PostgreSQL GIN tsvector indexes
+    # (on an IMMUTABLE wrapper around to_tsvector) backing Huginn::Searchable's
+    # :full_text strategy for every model that includes Huginn::Searchable.
+    #
+    #   rails g huginn:fts_indexes                       # all Searchable models
+    #   rails g huginn:fts_indexes Person Product        # specific models
+    #   rails g huginn:fts_indexes --dictionary english  # pick the dictionary
+    #
+    # The migration creates an IMMUTABLE public.f_tsvector(text) wrapper that
+    # pins the configured dictionary and the GIN indexes. Point the gem at the
+    # wrapper (to_tsvector itself is STABLE and cannot be indexed directly):
+    #
+    #   Huginn.configure { |c| c.search_strategy = :full_text;
+    #                        c.fts_dictionary = "portuguese";
+    #                        c.fts_function   = "public.f_tsvector" }
+    #
+    # Apply the same searchable model/association resolution as the trigram
+    # generator, so both index sets cover identical columns.
+    class FtsIndexesGenerator < Rails::Generators::Base
+      include SearchableColumns
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :model_names, type: :array, default: [], desc: "Models to index (default: all Searchable models)"
+
+      class_option :dictionary, type: :string, default: "portuguese",
+                                desc: "tsvector dictionary pinned by the IMMUTABLE wrapper"
+
+      def copy_migration
+        @entries = resolve_entries
+        @dictionary = options[:dictionary]
+        return if @entries.empty?
+
+        migration_template(
+          "add_huginn_fts_indexes.rb.tt",
+          "db/migrate/add_huginn_fts_indexes.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/huginn/fts_indexes/templates/add_huginn_fts_indexes.rb.tt

@@ -0,0 +1,24 @@
+class AddHuginnFtsIndexes < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+    # to_tsvector(regconfig, text) is STABLE (not IMMUTABLE), so it cannot be
+    # used in an index expression as-is. Wrap it in an IMMUTABLE function that
+    # always pins the configured dictionary.
+    execute <<~SQL
+      CREATE OR REPLACE FUNCTION public.f_tsvector(text)
+      RETURNS tsvector AS $$
+        SELECT to_tsvector('<%= @dictionary %>', $1);
+      $$
+      LANGUAGE sql IMMUTABLE PARALLEL SAFE;
+    SQL
+<% @entries.each do |entry| %>
+    add_index :<%= entry[:table] %>, "public.f_tsvector(<%= entry[:column] %>)", using: :gin, name: "index_<%= entry[:table] %>_<%= entry[:column] %>_fts"
+<% end %>
+  end
+
+  def down
+<% @entries.each do |entry| %>
+    remove_index :<%= entry[:table] %>, name: "index_<%= entry[:table] %>_<%= entry[:column] %>_fts"
+<% end %>
+    execute "DROP FUNCTION IF EXISTS public.f_tsvector(text)"
+  end
+end

data/lib/generators/huginn/searchable_columns.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Huginn
+  module Generators
+    # Shared logic between the index-scaffold generators
+    # (huginn:trigram_indexes / huginn:fts_indexes): resolving the Searchable
+    # models (or the explicit ones given as arguments) into the table/column
+    # pairs that need an index, and the migration filename machinery.
+    module SearchableColumns
+      extend ActiveSupport::Concern
+
+      included do
+        include Rails::Generators::Migration
+
+        # Rails::Generators::Migration leaves this as NotImplementedError; it
+        # is expected to be overridden to produce the next migration number.
+        def self.next_migration_number(dirname)
+          number = current_migration_number(dirname) + 1
+          ActiveRecord::Migration.next_migration_number(number)
+        end
+      end
+
+      private
+
+      def resolve_entries
+        models = if model_names.any?
+                   model_names.map { |name| constantize(name) }
+                 else
+                   ActiveRecord::Base.descendants
+                 end
+
+        models.filter_map do |model|
+          next unless model.respond_to?(:searchable_columns_config_resolved)
+
+          columns_for(model)
+        end.reject(&:empty?).flatten.uniq
+      end
+
+      def columns_for(model)
+        scope = []
+        resolved = model.searchable_columns_config_resolved
+
+        Array(resolved[:columns]).map(&:to_s).reject(&:blank?).each do |field|
+          scope << { table: model.table_name, column: field } if model.columns_hash.key?(field)
+        end
+
+        resolved[:associations].each do |assoc, cols|
+          reflection = model.reflect_on_association(assoc.to_sym)
+          next unless reflection
+
+          Array(cols).map(&:to_s).each do |col|
+            scope << { table: reflection.klass.table_name, column: col } if reflection.klass.columns_hash.key?(col)
+          end
+        end
+
+        scope
+      end
+
+      def constantize(klass_name)
+        klass_name.constantize
+      rescue NameError
+        raise Thor::Error, "Could not find model #{klass_name.inspect}"
+      end
+    end
+  end
+end

data/lib/generators/huginn/trigram_indexes/trigram_indexes_generator.rb

@@ -2,6 +2,7 @@
 
 require "rails/generators"
 require "rails/generators/migration"
+require "generators/huginn/searchable_columns"
 
 module Huginn
   module Generators
@@ -23,17 +24,12 @@ module Huginn
     # Indexes are only used when the :pg_trgm strategy is configured and the
     # pg_trgm/unaccent extensions are installed.
     class TrigramIndexesGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include SearchableColumns
 
       source_root File.expand_path("templates", __dir__)
 
       argument :model_names, type: :array, default: [], desc: "Models to index (default: all Searchable models)"
 
-      def self.next_migration_number(dirname)
-        next_migration_number = current_migration_number(dirname) + 1
-        ActiveRecord::Migration.next_migration_number(next_migration_number)
-      end
-
       def copy_migration
         @entries = resolve_entries
         return if @entries.empty?
@@ -43,48 +39,6 @@ module Huginn
           "db/migrate/add_huginn_trigram_indexes.rb"
         )
       end
-
-      private
-
-      def resolve_entries
-        models = if model_names.any?
-                   model_names.map { |name| constantize(name) }
-                 else
-                   ActiveRecord::Base.descendants
-                 end
-
-        models.filter_map do |model|
-          next unless model.respond_to?(:searchable_columns_config_resolved)
-
-          columns_for(model)
-        end.reject(&:empty?).flatten.uniq
-      end
-
-      def columns_for(model)
-        scope = []
-        resolved = model.searchable_columns_config_resolved
-
-        Array(resolved[:columns]).map(&:to_s).reject(&:blank?).each do |field|
-          scope << { table: model.table_name, column: field } if model.columns_hash.key?(field)
-        end
-
-        resolved[:associations].each do |assoc, cols|
-          reflection = model.reflect_on_association(assoc.to_sym)
-          next unless reflection
-
-          Array(cols).map(&:to_s).each do |col|
-            scope << { table: reflection.klass.table_name, column: col } if reflection.klass.columns_hash.key?(col)
-          end
-        end
-
-        scope
-      end
-
-      def constantize(klass_name)
-        klass_name.constantize
-      rescue NameError
-        raise Thor::Error, "Could not find model #{klass_name.inspect}"
-      end
     end
   end
 end

data/lib/huginn/configuration.rb

@@ -2,7 +2,8 @@
 
 module Huginn
   class Configuration
-    attr_accessor :pagy_items, :pagy_max_items, :unaccent_function
+    attr_accessor :pagy_items, :pagy_max_items, :unaccent_function,
+                  :fts_dictionary, :fts_function
     attr_writer :search_strategy, :auto_include_datatable, :auto_include_searchable
 
     def initialize
@@ -13,19 +14,37 @@ module Huginn
       # this at an IMMUTABLE wrapper (see `rails g huginn:trigram_indexes`),
       # e.g. "public.f_unaccent".
       @unaccent_function = "unaccent"
+      # The tsvector wrapper and dictionary used by the :full_text strategy. The
+      # wrapper (see `rails g huginn:fts_indexes`) pins the dictionary and is
+      # IMMUTABLE so GIN tsvector indexes are usable.
+      @fts_dictionary = "portuguese"
+      @fts_function = "public.f_tsvector"
       @search_strategy = :pg_trgm
       @auto_include_datatable = true
       @auto_include_searchable = true
     end
 
-    # :pg_trgm  -> trigram similarity (%) OR unaccent+ILIKE. The similarity
-    #              cutoff is the PostgreSQL GUC pg_trgm.similarity_threshold
-    #              (tune with SELECT set_limit(...)); a gin_trgm_ops GIN index
-    #              on UNACCENT(col) is used when present.
-    # :unaccent -> unaccent + ILIKE only
-    # :simple   -> plain LIKE
+    # :pg_trgm          -> trigram similarity (%) OR unaccent+ILIKE. The
+    #                      similarity cutoff is the PostgreSQL GUC
+    #                      pg_trgm.similarity_threshold (tune with
+    #                      SELECT set_limit(...)); a gin_trgm_ops GIN index on
+    #                      UNACCENT(col) is used when present.
+    # :full_text        -> PostgreSQL full text search (lexemes): the column is
+    #                      matched as to_tsvector(DICTIONARY, col) vs
+    #                      plainto_tsquery(DICTIONARY, term). Needs the
+    #                      fts_function wrapper and a GIN tsvector index.
+    # :unaccent         -> unaccent + ILIKE only
+    # :simple           -> plain LIKE
+    #
+    # Accepts a single symbol or an Array of symbols; when more than one is
+    # given the generated predicates are combined with OR (a row matches if
+    # any strategy matches).
     def search_strategy
-      @search_strategy.to_sym
+      if @search_strategy.is_a?(Array)
+        @search_strategy.map(&:to_sym)
+      else
+        @search_strategy.to_sym
+      end
     end
 
     def auto_include_datatable?

data/lib/huginn/datatable/association_path.rb

@@ -77,6 +77,12 @@ module Huginn
         nil
       end
 
+      # The Arel predicates folded in by the association scopes of every step.
+      # Public so subquery builders can replicate ActiveRecord's scoped joins.
+      def scope_constraints
+        scope_predicates
+      end
+
       # Reverse engineers a join spec usable by `ActiveRecord::Relation#joins`
       # for filter subqueries: `.joins(:people: { company: ... })`.
       def self.join_spec_for(names)

data/lib/huginn/searchable/fuzzy.rb

@@ -9,6 +9,11 @@ module Huginn
     #   :pg_trgm   -> trigram similarity (%) OR unaccent+ILIKE (best for typos).
     #                 Both branches are supported by a gin_trgm_ops GIN index
     #                 on UNACCENT(col); the index is used only when it exists.
+    #   :full_text -> PostgreSQL full text search: to_tsvector(col) @@
+    #                 plainto_tsquery(term), so morphological variants match;
+    #                 needs the IMMUTABLE fts_function wrapper and a GIN
+    #                 tsvector index. Effective with a single strategy or
+    #                 combined with :pg_trgm (OR).
     #   :unaccent  -> unaccent + ILIKE (case/accents insensitive)
     #   :simple    -> plain LIKE
     module Fuzzy
@@ -90,6 +95,45 @@ module Huginn
           Unaccent.new(@column, @value).predicate
         end
       end
+
+      # PostgreSQL full text search over lexemes:
+      #
+      #   public.f_tsvector(col) @@ plainto_tsquery('portuguese'::regconfig, term)
+      #
+      # The column side runs through the configured fts_function (an IMMUTABLE
+      # wrapper around to_tsvector that pins the dictionary, created by
+      # `rails g huginn:fts_indexes`) so a GIN tsvector index is usable. The
+      # query side uses plainto_tsquery, which ANDs the lexemes of the term and
+      # applies stemming — tolerant to morphological variants, blind to typos.
+      class FullText
+        def initialize(column, value, dictionary: nil)
+          @column = column
+          @value = value.to_s
+          @dictionary = dictionary || Huginn.configuration.fts_dictionary
+        end
+
+        def predicate
+          Arel::Nodes::InfixOperation.new("@@", tsvector, query)
+        end
+
+        private
+
+        def tsvector
+          Arel::Nodes::NamedFunction.new(Huginn.configuration.fts_function, [@column])
+        end
+
+        def query
+          Arel::Nodes::NamedFunction.new("plainto_tsquery", [regconfig, quoted_value])
+        end
+
+        def regconfig
+          Arel.sql("'#{@dictionary}'::regconfig")
+        end
+
+        def quoted_value
+          Arel::Nodes.build_quoted(@value, @column)
+        end
+      end
     end
   end
-end
+end

data/lib/huginn/searchable/query.rb

@@ -6,14 +6,22 @@ module Huginn
   module Searchable
     AssociationPath = Datatable::AssociationPath unless const_defined?(:AssociationPath)
     # Builds a tolerant full-text search relation over a model's searchable
-    # columns.
+    # columns. The matching predicate per column is driven by
+    # Huginn.configuration.search_strategy (:pg_trgm, :full_text, :unaccent,
+    # :simple — or an Array of them combined with OR).
     #
     # Columns are split in two groups following the datatable pattern:
     #
     #   * the model's own columns  -> direct fuzzy predicates on the base WHERE
-    #   * association columns      -> semi-join subqueries on the primary key
-    #                                  pk IN (SELECT DISTINCT pk FROM base
-    #                                       JOIN <chain> ... WHERE <fuzzy>)
+    #   * association columns      -> reverse semi-join subqueries anchored on
+    #                                  the first FK/has_many hop, so the base
+    #                                  table is never re-scanned:
+    #
+    #        belongs_to ->  base[fk] IN (SELECT DISTINCT t1[pk]  FROM t1 ...)
+    #        has_many   ->  base[pk]  IN (SELECT DISTINCT t1[fk] FROM t1 ...)
+    #
+    # Through/hand-joined chains keep the generic fallback:
+    #        base[pk] IN (SELECT DISTINCT base[pk] FROM base JOIN <chain> ...)
     #
     # The base relation never carries joins, so every match group stays one
     # query and the count remains a plain COUNT(*). Multiple association
@@ -36,9 +44,9 @@ module Huginn
 
         resolution = resolve_columns
         predicates = fuzzy_predicates(resolution.fetch(:own))
-        resolution.fetch(:associations).each do |chain, attrs|
-          subquery = association_subquery(chain, attrs)
-          predicates << arel_table[primary_key].in(subquery.arel) if subquery
+        resolution.fetch(:associations).each do |_chain, group|
+          predicate = association_predicate(group)
+          predicates << predicate if predicate
         end
 
         return apply_distinct(relation) if predicates.empty?
@@ -49,13 +57,13 @@ module Huginn
       private
 
       def fuzzy_predicates(attrs)
-        attrs.map { |attr| fuzzy_predicate(attr) }
+        attrs.map { |attr| fuzzy_predicate(attr) }.compact
       end
 
       def resolve_columns
         columns = @model.searchable_columns_config_resolved
         own = []
-        associations = Hash.new { |hash, key| hash[key] = [] }
+        associations = Hash.new { |hash, key| hash[key] = { path: nil, attrs: [] } }
 
         Array(columns[:columns]).map(&:to_s).reject(&:blank?).each do |field|
           if field.include?(".")
@@ -78,35 +86,109 @@ module Huginn
         return unless path.valid?
         return unless path.target_klass.columns_hash.key?(path.column)
 
-        groups[path.association_names] << path.target_table[path.column]
+        group = groups[path.association_names]
+        group[:path] ||= path
+        group[:attrs] << path.target_table[path.column]
+      end
+
+      # Prefers the FK-anchored reverse semi-join; falls back to the generic
+      # pk subquery for through chains or anything the reverse plan rejects.
+      def association_predicate(group)
+        path = group[:path]
+        attrs = group[:attrs]
+        return nil if path.nil? || attrs.empty?
+
+        anchored_predicate(path, attrs)
+      rescue StandardError
+        generic_predicate(path, attrs)
+      end
+
+      # Reverse semi-join:
+      #
+      #   belongs_to -> base[fk]  IN (SELECT DISTINCT t1[join_pk]  FROM t1 ...)
+      #   has_many   -> base[pk]   IN (SELECT DISTINCT t1[fk]      FROM t1 ...)
+      #
+      # Walks the chain from the first target table outwards so the base table
+      # is never scanned inside the subquery.
+      def anchored_predicate(path, attrs)
+        if through_association?(path)
+          return generic_predicate(path, attrs)
+        end
+
+        steps = path.resolved_steps
+        first = steps.first
+        reflection = first.reflection
+
+        outer = if reflection.belongs_to?
+                  arel_table[reflection.foreign_key]
+                else
+                  arel_table[reflection.active_record_primary_key]
+                end
+
+        projection = if reflection.belongs_to?
+                       first.table[reflection.join_primary_key]
+                     else
+                       first.table[reflection.foreign_key]
+                     end
+
+        manager = Arel::SelectManager.new
+        manager.from(first.table)
+        steps.drop(1).each { |step| manager.join(step.table).on(step.link_to_previous) }
+        manager.where(fuzzy_predicates(attrs).reduce(&:or))
+        path.scope_constraints.each { |constraint| manager.where(constraint) }
+        manager.project(projection)
+        manager.distinct
+
+        outer.in(manager)
+      end
+
+      # Whether the first hop goes through a join model; the FK anchoring is
+      # ambiguous there so the generic pk subquery is used instead.
+      def through_association?(path)
+        reflection = @model.reflect_on_association(path.segments.first.to_sym)
+        reflection.is_a?(ActiveRecord::Reflection::ThroughReflection)
       end
 
-      # Semi-join subquery over the base table: DISTINCT pk while joining the
-      # association chain of the group and applying the fuzzy predicates on the
-      # target columns. Mirrors datatable's association_ids_subquery.
-      def association_subquery(chain, attrs)
-        return nil if chain.empty?
+      # Generic fallback semi-join subquery over the base table, mirroring
+      # datatable's association_ids_subquery:
+      #   base[pk] IN (SELECT DISTINCT base[pk] FROM base JOIN <chain> ...).
+      def generic_predicate(path, attrs)
+        return nil unless path
 
-        spec = AssociationPath.join_spec_for(chain.map(&:to_sym))
+        spec = AssociationPath.join_spec_for(path.association_names.map(&:to_sym))
         base = @model.all.except(:select, :order, :offset, :limit)
                         .select(arel_table[primary_key])
                         .distinct
 
         predicate = fuzzy_predicates(attrs).reduce(&:or)
-        base.joins(spec).where(predicate)
+        arel_table[primary_key].in(base.joins(spec).where(predicate).arel)
       end
 
       def fuzzy_predicate(attr)
-        case strategy
+        strategies = Array(strategy)
+        predicates = strategies.map { |strat| predicate_for_strategy(attr, strat) }.compact
+        return nil if predicates.empty?
+
+        predicates.reduce(&:or)
+      end
+
+      def predicate_for_strategy(attr, strat)
+        case strat
         when :pg_trgm
           if pg_trgm_available?
             Fuzzy::Trigram.new(attr, @value).predicate
           else
             fallback_fuzzy(attr)
           end
+        when :full_text
+          if fts_available?
+            Fuzzy::FullText.new(attr, @value).predicate
+          else
+            fallback_fuzzy(attr)
+          end
         when :unaccent
           Fuzzy::Unaccent.new(attr, @value).predicate
-        else
+        when :simple
           Fuzzy::Simple.new(attr, @value).predicate
         end
       end
@@ -135,6 +217,27 @@ module Huginn
         @unaccent_available ||= extension_installed?("unaccent")
       end
 
+      # Whether the IMMUTABLE tsvector wrapper behind the :full_text strategy
+      # exists (created by `rails g huginn:fts_indexes`). FTS is core
+      # PostgreSQL, but without the wrapper the predicate would raise, so we
+      # degrade to the unaccent fallback instead.
+      def fts_available?
+        return false unless postgresql?
+        @fts_available ||= begin
+          schema, name = split_function_name(Huginn.configuration.fts_function)
+          @model.connection.select_value(
+            ActiveRecord::Base.sanitize_sql_array(
+              ["SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = ? AND p.proname = ?", schema, name]
+            )
+          ).present?
+        end
+      end
+
+      def split_function_name(function)
+        schema, _, name = function.to_s.rpartition(".")
+        [schema.presence || "public", name]
+      end
+
       def extension_installed?(name)
         @model.connection
               .select_all(sanitize_extension_query(name))

data/lib/huginn/searchable/searchable.rb

@@ -36,11 +36,15 @@ module Huginn
       end
 
       def searchable_columns_config_resolved
-        config = searchable_columns_config || {}
-        {
-          columns: config[:columns].presence || default_searchable_columns,
-          associations: config[:associations] || {}
-        }
+        config = searchable_columns_config
+        if config.nil?
+          { columns: default_searchable_columns, associations: {} }
+        else
+          {
+            columns: Array(config[:columns]),
+            associations: config[:associations] || {}
+          }
+        end
       end
 
       private

data/lib/huginn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Huginn
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: huginn_datatable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kayky Marcelo
@@ -139,6 +139,9 @@ files:
 - LICENSE.txt
 - README.md
 - README.pt-BR.md
+- lib/generators/huginn/fts_indexes/fts_indexes_generator.rb
+- lib/generators/huginn/fts_indexes/templates/add_huginn_fts_indexes.rb.tt
+- lib/generators/huginn/searchable_columns.rb
 - lib/generators/huginn/trigram_indexes/templates/add_huginn_trigram_indexes.rb.tt
 - lib/generators/huginn/trigram_indexes/trigram_indexes_generator.rb
 - lib/huginn.rb