huginn_datatable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7014d31503c76a5637c2bd15b82b8cf2be1c173ef11575a9325ec8457d7c65e
-  data.tar.gz: 175542cecf2d1378d0fa571ef538c0f2cccf24d6acab94bb3e0b398e97926261
+  metadata.gz: e68c742da97818c79b41681099972a3e4c3cc4613b8500831226abe09b2a87ed
+  data.tar.gz: 855168e5b6bbc9df1bceb381484bf20f550fcf57c0d0a35d6aba15c50b20a775
 SHA512:
-  metadata.gz: 951dcb3aeb617bc98b23fc8e883e0fa06d572ff312e0888171b17a26b70454eddbf84972bc6dfd91589a3788ac188266d1282d9122f53522923094ebdec0017c
-  data.tar.gz: 21ed148247e3e9d3a9cff2682d4d19c15c4bdf7806fd0222c4018f829a98fde7f52720e8219e2caaaa929d8c778f5ccc6b7933de9b2245bc6b597c89f27a7745
+  metadata.gz: f345b93074fec47d95589bdc06078b5c2585a79e0fd2a7c02c519d3ca35baa286a885f94278a64048004891a139f4c97a293848cf094523cbcff85ccc2276ce5
+  data.tar.gz: d2bfa72d92cc096dba420c20e2a9bc0b26f466e0b981b5d9e653d6f5f2dc33c105c5fd12a1c3e3269691ecafd0704efabaec80943f166b610798066420c3fd81

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ### 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(*)`.
+
 #### 0.2.0
 
 - **Breaking:** `:pg_trgm` search now uses the PostgreSQL `%` operator (`UNACCENT(col) % UNACCENT('term')`), driven by the **indexable** operator instead of a bare `similarity()` comparison. A `gin_trgm_ops` GIN index on `UNACCENT(col)` is used when present (BitmapOr over the same index with the ILIKE branch); without it, results stay correct via sequential scan.

data/README.md

@@ -18,7 +18,7 @@ Huginn is a lightweight query layer for Rails that turns a raw datatable request
 ## Highlights
 
 - **Two-phase execution** — association filters/orders/range become reflection-secured subqueries, then a lean count and `preload` **only on the paginated subset**.
-- **Lean counts** — `COUNT(DISTINCT pk)` through a stripped relation; no JOIN materialization.
+- **Lean counts** — the base relation never joins (`COUNT(*)` over a stripped relation); association matches run as pk subqueries instead.
 - **SQL injection safe ordering/filtering** — every column reference is resolved through Arel reflection, never string-interpolated.
 - **Accent/typo tolerant search** — `pg_trgm` similarity (`%` operator) OR `unaccent+ILIKE`, with a configurable fallback chain; uses a `gin_trgm_ops` GIN index when one exists.
 - **Rails conventions** — works with `ActionController::Parameters`, Railtie auto-includes both concerns (toggleable), zero boilerplate.
@@ -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:
@@ -129,7 +142,7 @@ Any `column` **or** `association.column` reference is validated and mapped to it
 Plano.datatable({ orders: [{ "operadora.pessoa.nome" => "asc" }] }, allowed_paths: [{ operadora: :pessoa }])
 ```
 
-> Association filters/range and ordering use reflection-resolved subqueries (see the "allowlist of associations" section below). The main relation stays singular and the count is `COUNT(DISTINCT pk)`.
+> Association filters/range, ordering and search use reflection-resolved subqueries (see the "allowlist of associations" section below). The base relation stays singular and join-free, so the count is a plain `COUNT(*)`.
 
 ## Association allowlist (`allowed_paths`)
 
@@ -185,7 +198,7 @@ class Person < ApplicationRecord
   searchable_columns :name, company: [:name, :cnpj]
 end
 
-Person.search("globex")                            # matches company.name via a left_join
+Person.search("globex")                            # matches company.name via a pk subquery
 Person.search("kayky", distinct: false)            # disable the implicit DISTINCT
 ```
 
@@ -235,7 +248,7 @@ Notes:
 
 ```
 phase 1  build the relation          subqueries (pk IN … / ORDER BY (SELECT …)) + search + filters + order   (no data in memory)
-phase 2  count                       SELECT COUNT(DISTINCT "<pk column>") ... (subquery, pk-indexed)
+phase 2  count                       SELECT COUNT(*) ... (base relation is join-free)
           paginate                   offset / limit
           preload                    SELECT ... WHERE id IN (subset)        (2nd lightweight query)
 ```
@@ -257,7 +270,7 @@ lib/huginn/datatable/filter_normalizer.rb  functional param normalization
 lib/huginn/datatable/paginator.rb    lean count, pagination, isolated preload
 lib/huginn/searchable.rb            Huginn::Searchable (aggregator)
 lib/huginn/searchable/searchable.rb the search Concern + DSL
-lib/huginn/searchable/query.rb      tolerant search builder (joins + OR)
+lib/huginn/searchable/query.rb      tolerant search builder (subqueries + OR)
 lib/huginn/searchable/fuzzy.rb      pg_trgm / unaccent / simple predicates
 lib/generators/...                  `huginn:trigram_indexes` (GIN index migrations)
 ```

data/README.pt-BR.md

@@ -18,7 +18,7 @@ O Huginn é uma camada de consulta leve para Rails que transforma uma requisiç
 ## Destaques
 
 - **Execução em duas fases** — filtros/orders/ranges de associação se tornam subqueries resolvidas por reflexão, e o `preload` é feito **somente no subconjunto paginado**.
-- **Counts enxutos** — `COUNT(DISTINCT pk)` através de uma relation restrita, sem materialização de JOINs.
+- **Counts enxutos** — a relation base nunca faz join (`COUNT(*)` sobre uma relation restrita); as buscas de associação acontecem via subqueries no pk.
 - **Ordenação/filtro seguros contra SQL injection** — toda referência de coluna é resolvida via reflexão do Arel, nunca interpolada como string.
 - **Busca tolerante a acentos/typos** — similaridade `pg_trgm` (operador `%`) OU `unaccent+ILIKE`, com cadeia de fallback configurável; usa índice GIN `gin_trgm_ops` quando existente.
 - **Convenções do Rails** — funciona com `ActionController::Parameters`, Railtie inclui ambos os concerns automaticamente (desligável), zero boilerplate.
@@ -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:
@@ -129,7 +142,7 @@ Qualquer referência `column` **ou** `associacao.column` é validada e mapeada p
 Plano.datatable({ orders: [{ "operadora.pessoa.nome" => "asc" }] }, allowed_paths: [{ operadora: :pessoa }])
 ```
 
-> Filtros/ranges e order de associação usam subqueries resolvidas por reflexão (veja a seção "Allowlist de associações" abaixo). A relation principal permanece única e o count é `COUNT(DISTINCT pk)`.
+> Filtros/ranges, order e busca de associação usam subqueries resolvidas por reflexão (veja a seção "Allowlist de associações" abaixo). A relation base permanece única e sem joins, então o count é um `COUNT(*)` simples.
 
 ## Allowlist de associações (`allowed_paths`)
 
@@ -185,7 +198,7 @@ class Person < ApplicationRecord
   searchable_columns :name, company: [:name, :cnpj]
 end
 
-Person.search("globex")                            # encontra company.name via left_join
+Person.search("globex")                            # encontra company.name via subquery no pk
 Person.search("kayky", distinct: false)            # desativa o DISTINCT implícito
 ```
 
@@ -235,7 +248,7 @@ Observações:
 
 ```
 fase 1  construir a relation      subqueries (pk IN … / ORDER BY (SELECT …)) + search + filters + order   (sem dados em memória)
-fase 2  count                     SELECT COUNT(DISTINCT "<pk>") ... (subquery, indexada por pk)
+fase 2  count                     SELECT COUNT(*) ... (relation base sem joins)
         paginate                  offset / limit
         preload                   SELECT ... WHERE id IN (subset)        (2ª query leve)
 ```
@@ -257,7 +270,7 @@ lib/huginn/datatable/filter_normalizer.rb  normalização funcional de params
 lib/huginn/datatable/paginator.rb  count enxuto, paginação, preload isolado
 lib/huginn/searchable.rb            Huginn::Searchable (agregador)
 lib/huginn/searchable/searchable.rb o Concern do search + DSL
-lib/huginn/searchable/query.rb      construtor de busca tolerante (joins + OR)
+lib/huginn/searchable/query.rb      construtor de busca tolerante (subqueries + OR)
 lib/huginn/searchable/fuzzy.rb      predicados pg_trgm / unaccent / simple
 lib/generators/...                  gerador `huginn:trigram_indexes` (migrations de índices GIN)
 ```

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/datatable/paginator.rb

@@ -10,10 +10,9 @@ module Huginn
     #   2. count lean, paginate with Pagy, then preload associations only
     #      on the small paginated subset.
     #
-    # The count runs against a stripped relation (no select/includes/order/
-    # offset/limit) selecting only the primary key with DISTINCT, so that
-    # PostgreSQL answers it through the PK index as a subquery instead of a
-    # massive COUNT(DISTINCT ...) over the joins.
+    # The base relation never carries joins (association filters, ranges,
+    # orders and the search are all resolved through primary-key subqueries),
+    # so the count stays a plain COUNT(*) over the stripped relation.
     class Paginator
       attr_reader :relation, :params, :includes
 
@@ -77,10 +76,7 @@ module Huginn
       end
 
       def total_count
-        stripped = relation.except(:select, :includes, :order, :offset, :limit)
-        return stripped.count unless stripped.left_outer_joins_values.any? || stripped.joins_values.any?
-
-        stripped.select(stripped.arel_table[stripped.primary_key]).distinct.count
+        relation.except(:select, :includes, :order, :offset, :limit).count
       end
 
       def config

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

@@ -1,13 +1,31 @@
 # frozen_string_literal: true
 
+require_relative "../datatable/association_path"
+
 module Huginn
   module Searchable
+    AssociationPath = Datatable::AssociationPath unless const_defined?(:AssociationPath)
     # Builds a tolerant full-text search relation over a model's searchable
-    # columns, optionally crossing associations through left_joins.
+    # 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      -> reverse semi-join subqueries anchored on
+    #                                  the first FK/has_many hop, so the base
+    #                                  table is never re-scanned:
     #
-    # All matched columns are fused into a single Arel OR predicate, so the
-    # whole search stays one query regardless of how many columns (or
-    # associations) are involved.
+    #        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
+    # chains produce one subquery each, combined with OR.
     class Query
       def self.call(model, value, options = {})
         new(model, value, options).call
@@ -25,58 +43,152 @@ module Huginn
         return apply_distinct(relation) if @value.strip.empty?
 
         resolution = resolve_columns
-        return apply_distinct(relation) if resolution.fetch(:attrs).empty?
+        predicates = fuzzy_predicates(resolution.fetch(:own))
+        resolution.fetch(:associations).each do |_chain, group|
+          predicate = association_predicate(group)
+          predicates << predicate if predicate
+        end
 
-        joins = resolution.fetch(:joins)
-        relation = relation.left_joins(*joins) if joins.any?
+        return apply_distinct(relation) if predicates.empty?
 
-        predicate = resolution.fetch(:attrs).map { |attr| fuzzy_predicate(attr) }.reduce(&:or)
-        apply_distinct(relation.where(predicate))
+        apply_distinct(relation.where(predicates.reduce(&:or)))
       end
 
       private
 
+      def fuzzy_predicates(attrs)
+        attrs.map { |attr| fuzzy_predicate(attr) }.compact
+      end
+
       def resolve_columns
         columns = @model.searchable_columns_config_resolved
-        joins = []
-        attrs = []
+        own = []
+        associations = Hash.new { |hash, key| hash[key] = { path: nil, attrs: [] } }
 
         Array(columns[:columns]).map(&:to_s).reject(&:blank?).each do |field|
           if field.include?(".")
-            name, col = field.split(".", 2)
-            push_association(joins, attrs, name, col)
+            chain, column = field.split(".", 2)
+            push_association(associations, chain, column)
           else
-            attrs << @model.arel_table[field] if @model.columns_hash.key?(field)
+            own << @model.arel_table[field] if @model.columns_hash.key?(field)
           end
         end
 
         columns[:associations].each do |name, cols|
-          Array(cols).each { |col| push_association(joins, attrs, name.to_s, col.to_s) }
+          Array(cols).each { |column| push_association(associations, name.to_s, column.to_s) }
         end
 
-        { joins: joins.uniq, attrs: attrs }
+        { own: own, associations: associations }
+      end
+
+      def push_association(groups, chain, column)
+        path = AssociationPath.call(@model, "#{chain}.#{column}")
+        return unless path.valid?
+        return unless path.target_klass.columns_hash.key?(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
 
-      def push_association(joins, attrs, name, col)
-        association = @model.reflect_on_association(name.to_sym)
-        return unless association
+      # 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
 
-        table = association.klass.arel_table
-        attrs << table[col] if association.klass.columns_hash.key?(col)
-        joins << name.to_sym unless joins.include?(name.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)
+        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
@@ -105,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))
@@ -121,6 +254,14 @@ module Huginn
         @model.connection.adapter_name.downcase.include?("postgres")
       end
 
+      def arel_table
+        @model.arel_table
+      end
+
+      def primary_key
+        @model.primary_key
+      end
+
       def apply_distinct(relation)
         @distinct ? relation.distinct : relation
       end

data/lib/huginn/searchable/searchable.rb

@@ -17,8 +17,8 @@ module Huginn
       #
       # When nothing is declared, every :string/:text column of the model is
       # searched automatically. Columns may be association-scoped ("person.name")
-      # or declared via keyword arguments; scoped columns are reached through a
-      # left_join.
+      # or declared via keyword arguments; scoped columns are resolved through
+      # semi-join subqueries on the primary key (no joins on the base relation).
       def searchable_columns(*columns, **associations)
         self.searchable_columns_config = {
           columns: columns.flatten.compact.map(&:to_s),
@@ -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.0"
+  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.0
+  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