huginn_datatable 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '05719914312baa1225e26059bd5154312ee5df8bc369df6f5f9676d423ed9d0e'
-  data.tar.gz: b876f81b7add7781a4bd6b7424e3674f251c09ecfe38e0a70e8f891bb2286c76
+  metadata.gz: 82a13098551b25e1b656beb853926f7dcbc964c420a64dde0e22182f735a02bb
+  data.tar.gz: abdcf5e8f489ad2b6bff0870bde97d443247f6d31b0efc93274a47da81837916
 SHA512:
-  metadata.gz: bed2c0bc55d70a6ceaa57a6a84fb264360df75cbab4f42a2a82031073fdd0f15778b1681afcdc35aba31a478e4e8c18a6acfc960b725a1018306211845e72c72
-  data.tar.gz: 8f58d9e3fec2d2a38350dc010f9b68d6ab60449e27338291dfae8ae7bcaba2b96cbb64f945067487c1ed97889c6642bbb451dfde21644b0170e708ae109aa30a
+  metadata.gz: 3a03a5dc06c8f00d4a66a9bd9af8d06ddc2a9a910dbbb5c8a392985f4b0a21a89439d40829d20559232e1a04d2978444fdcf1c39ac86ce20c176af3fbb98a1de
+  data.tar.gz: b229398a323d43253aba96f667ca27dc5d76eacdf3bec68d84cb51c482e8838914de5289fdc9093a293016743f5e14c69acdc5b60705ba9e57306d639b86ca74

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ### Unreleased
 
+#### 0.4.0
+
+- **PostgreSQL array columns in `filters`** (`uuid[]`, `text[]`, `string[]`...), for own columns, `huginn_attributes` aliases and association-scoped columns. The payload is unchanged:
+  - one value → the row contains it (`col @> ARRAY[v]`);
+  - several values → **any** of them (`col && ARRAY[...]`, the same semantics as `IN`), or **all** of them (`col @> ARRAY[...]`) when the field is declared with `array: :all`;
+  - `"null"` → empty (or NULL) array, combinable with values.
+- New `huginn_array_match :field, :all` and `huginn_attributes alias: { column: "table.col", array: :all }` to choose the match mode (default `:any`).
+- Array filter values are cast by the element type (invalid values — e.g. a malformed UUID — are dropped, never reaching SQL) and the literal is built from quoted values only.
+- `filters` accept a Hash whose value is an Array (`filters[col][]=a&filters[col][]=b` → `{ "col" => [a, b] }`) as several values (IN / array match), the same as repeating the key. Before, the Array was taken as one value and never matched.
+- **Fix:** default searchable columns no longer include array columns (`string[]`/`text[]`), which broke `search` with `unaccent(character varying[]) does not exist`.
+
+#### 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

@@ -13,14 +13,14 @@
   🇺🇸 English · <a href="./README.pt-BR.md">🇧🇷 Português</a>
 </p>
 
-Huginn is a lightweight query layer for Rails that turns a raw datatable request into a **lean count, a paginated subset and one preload** — instead of a massive JOIN materialized in memory. It also ships a PostgreSQL fuzzy-search builder (`pg_trgm` similarity via the `%` operator with `unaccent` and `ILIKE` fallback) that is tolerant to typos and accents — and that can lean on a GIN index when present.
+Huginn is a lightweight query layer for Rails that turns a raw datatable request into a **lean count, a paginated subset and one preload** — instead of a massive JOIN materialized in memory. It also ships a PostgreSQL tolerant-search builder (`pg_trgm` similarity via the `%` operator with `unaccent` and `ILIKE` fallback, plus a `:full_text` lexeme strategy) that is tolerant to typos and accents — and that can lean on GIN indexes when present.
 
 ## 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** — 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.
+- **Tolerant search** — `pg_trgm` similarity (`%` operator) OR `unaccent+ILIKE` (typo/acent tolerant) and `:full_text` over lexemes (morphology-aware); strategies are `search_strategy`-selectable or combined with OR, backed by GIN indexes when present.
 - **Rails conventions** — works with `ActionController::Parameters`, Railtie auto-includes both concerns (toggleable), zero boilerplate.
 
 ## Development
@@ -58,7 +58,7 @@ The `gemfiles/*.gemfile` are generated by Appraisal (committed); their `.lock` f
 ## Installation
 
 ```ruby
-gem "huginn"
+gem "huginn_datatable", require: "huginn"
 ```
 
 ## Configuration
@@ -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:
@@ -107,7 +120,7 @@ result = Plano.datatable(
   includes: [{ operadora: { pessoa: [:endereco, :contatos] } }] # preloaded on the page only
 )
 
-result[:total_count] # Integer (lean COUNT DISTINCT pk)
+result[:total_count] # Integer (lean COUNT(*))
 result[:data]        # ActiveRecord::Relation (paged + preloaded)
 ```
 
@@ -117,10 +130,32 @@ Supported params:
 |---|---|
 | `page`, `per_page` | Pagination (clamped to `pagy_max_items`) |
 | `search` | Delegates to `Huginn::Searchable.search` |
-| `filters` | Hash / Array of hashes / pairs -> exact or `IN` conditions (`"col" => "null"` → `IS NULL`) |
+| `filters` | Hash (`{ "col" => v }` or `{ "col" => [a, b] }`) / Array of hashes / pairs -> exact or `IN` conditions (`"col" => "null"` → `IS NULL`) |
 | `range_data` | `{ "created_at" => ["2024-01-01", "2024-12-31"] }` — date or numeric ranges |
 | `orders` | `[{ "pessoa.nome" => "desc" }]` — plain or association-scoped columns |
 
+### Array columns (PostgreSQL)
+
+`filters` also work on array columns (`uuid[]`, `text[]`, `string[]`...) — own, aliased or association-scoped — with the same payload:
+
+```ruby
+Person.datatable({ filters: { tag_ids: id } })                          # contains id        (tag_ids @> ARRAY[id])
+Person.datatable({ filters: [{ tag_ids: a }, { tag_ids: b }] })          # contains a OR b    (tag_ids && ARRAY[a, b])
+Person.datatable({ filters: { tag_ids: "null" } })                       # empty array
+```
+
+Several values match **any** of them by default (like `IN`). To require **all** of them:
+
+```ruby
+class Person < ApplicationRecord
+  huginn_array_match :tag_ids, :all
+  # or, with an alias:
+  huginn_attributes tags: { column: "people.tag_ids", array: :all }
+end
+```
+
+Values are cast by the element type (an invalid UUID is dropped, never sent to the database) and the array literal is built from quoted values only. Array columns are left out of the default `search` columns.
+
 ### Scoped ordering / filtering
 
 Any `column` **or** `association.column` reference is validated and mapped to its real reflected table:
@@ -189,6 +224,14 @@ Person.search("globex")                            # matches company.name via a
 Person.search("kayky", distinct: false)            # disable the implicit DISTINCT
 ```
 
+`searchable_columns columns: []` is honored: an empty array means "search only the declared associations" — it no longer falls back to the model's own `:string`/`:text` columns:
+
+```ruby
+class Person < ApplicationRecord
+  searchable_columns columns: [], company: [:name, :cnpj]  # only company.name/cnpj are searched
+end
+```
+
 `Huginn::Datatable` reuses `Huginn::Searchable.search` automatically when the model responds to `search`.
 
 ## Trigram indexes (performance)
@@ -231,6 +274,51 @@ Notes:
 - Only helpful for search terms of **3 or more characters** — trigrams need that many to match. Shorter terms always scan.
 - To see it working, run a `Person.search("term").explain` with the wrapper configured and a `gin_trgm_ops` index present.
 
+## Full-text indexes (performance)
+
+Under `:full_text`, each searchable column produces a lexeme predicate backed by a GIN tsvector index:
+
+```sql
+public.f_tsvector(col) @@ plainto_tsquery('portuguese'::regconfig, 'term')
+```
+
+Because `to_tsvector()` is `STABLE` (not `IMMUTABLE`), it cannot be indexed directly — you need an `IMMUTABLE` wrapper that pins the dictionary plus an expression index on it:
+
+```sql
+CREATE OR REPLACE FUNCTION public.f_tsvector(text)
+RETURNS tsvector AS $$
+  SELECT to_tsvector('portuguese'::regconfig, $1);
+$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
+
+CREATE INDEX index_people_name_fts ON people USING gin (public.f_tsvector(name));
+```
+
+Then point the gem at the wrapper and dictionary:
+
+```ruby
+Huginn.configure do |c|
+  c.search_strategy = :full_text
+  c.fts_dictionary  = "portuguese"
+  c.fts_function    = "public.f_tsvector"
+end
+```
+
+Or scaffold the migration for every Searchable model (wrapper + GIN indexes included), picking a dictionary via `--dictionary`:
+
+```sh
+rails g huginn:fts_indexes                               # all Searchable models
+rails g huginn:fts_indexes Person Product                # specific models
+rails g huginn:fts_indexes --dictionary english          # pin a different dictionary
+```
+
+The index is **optional** — without the wrapper/index the search degrades gracefully to the unaccent+ILIKE fallback and stays correct (via sequential scan).
+
+Notes:
+
+- Requires the full text search support bundled with PostgreSQL (no extra extension).
+- `:full_text` has no typo tolerance — combine it with `:pg_trgm` (`search_strategy: [:pg_trgm, :full_text]`) and generate **both** index sets (`huginn:trigram_indexes` + `huginn:fts_indexes`).
+- To see it working, run a `Person.search("term").explain` with the wrapper configured and a GIN tsvector index present.
+
 ## Query efficiency
 
 ```
@@ -246,7 +334,7 @@ For a `Plano` datatable with deep `includes:`, this is exactly **2 extra queries
 
 ```
 lib/huginn.rb                       entry, Huginn.configure, Huginn.instrument
-lib/huginn/configuration.rb         search_strategy, unaccent_function, pagy_*
+lib/huginn/configuration.rb         search_strategy, unaccent_function, fts_*, pagy_*
 lib/huginn/railtie.rb               auto-includes concerns into ActiveRecord
 lib/huginn/datatable.rb             Huginn::Datatable (aggregator)
 lib/huginn/datatable/datatable.rb   the datatable Concern
@@ -258,8 +346,8 @@ 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 (subqueries + OR)
-lib/huginn/searchable/fuzzy.rb      pg_trgm / unaccent / simple predicates
-lib/generators/...                  `huginn:trigram_indexes` (GIN index migrations)
+lib/huginn/searchable/fuzzy.rb      pg_trgm / full_text / unaccent / simple predicates
+lib/generators/...                  `huginn:trigram_indexes` + `huginn:fts_indexes` (GIN index migrations)
 ```
 
 ## Instrumentation

data/README.pt-BR.md

@@ -13,14 +13,14 @@
   <a href="./README.md">🇺🇸 English</a> · 🇧🇷 Português
 </p>
 
-O Huginn é uma camada de consulta leve para Rails que transforma uma requisição de datatable bruta em um **count enxuto, um subconjunto paginado e um único preload** — em vez de um JOIN enorme materializado em memória. Também traz um construtor de busca *fuzzy* para PostgreSQL (similaridade `pg_trgm` via operador `%` com `unaccent` e fallback `ILIKE`) tolerante a erros de digitação e acentuação — e que pode usar um índice GIN quando presente.
+O Huginn é uma camada de consulta leve para Rails que transforma uma requisição de datatable bruta em um **count enxuto, um subconjunto paginado e um único preload** — em vez de um JOIN enorme materializado em memória. Também traz um construtor de busca tolerante a erros para PostgreSQL (similaridade `pg_trgm` via operador `%` com `unaccent` e fallback `ILIKE`, além da estratégia `:full_text` sobre lexemas) que tolera erros de digitação e acentuação — e que pode usar índices GIN quando presentes.
 
 ## 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** — 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.
+- **Busca tolerante** — similaridade `pg_trgm` (operador `%`) OU `unaccent+ILIKE` (tolerante a typos/acentos) e `:full_text` sobre lexemas (ciente de morfologia); as estratégias são selecionáveis via `search_strategy` ou combinadas com OR, respaldadas por índices GIN quando presentes.
 - **Convenções do Rails** — funciona com `ActionController::Parameters`, Railtie inclui ambos os concerns automaticamente (desligável), zero boilerplate.
 
 ## Desenvolvimento
@@ -58,7 +58,7 @@ Os `gemfiles/*.gemfile` são gerados pelo Appraisal (commitados); os arquivos `.
 ## Instalação
 
 ```ruby
-gem "huginn"
+gem "huginn_datatable", require: "huginn"
 ```
 
 ## Configuração
@@ -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:
@@ -107,7 +120,7 @@ result = Plano.datatable(
   includes: [{ operadora: { pessoa: [:endereco, :contatos] } }] # preload somente na página
 )
 
-result[:total_count] # Integer (count enxuto COUNT DISTINCT pk)
+result[:total_count] # Integer (count enxuto COUNT(*))
 result[:data]        # ActiveRecord::Relation (paginada + preloaded)
 ```
 
@@ -117,10 +130,32 @@ Parâmetros suportados:
 |---|---|
 | `page`, `per_page` | Paginação (limitada a `pagy_max_items`) |
 | `search` | Delega para `Huginn::Searchable.search` |
-| `filters` | Hash / Array de hashes / pares -> condições exatas ou `IN` (`"col" => "null"` → `IS NULL`) |
+| `filters` | Hash (`{ "col" => v }` ou `{ "col" => [a, b] }`) / Array de hashes / pares -> condições exatas ou `IN` (`"col" => "null"` → `IS NULL`) |
 | `range_data` | `{ "created_at" => ["2024-01-01", "2024-12-31"] }` — ranges de datas ou numéricos |
 | `orders` | `[{ "pessoa.nome" => "desc" }]` — colunas simples ou de associação |
 
+### Colunas array (PostgreSQL)
+
+Os `filters` também funcionam em colunas array (`uuid[]`, `text[]`, `string[]`...) — próprias, com alias ou de associação — com o mesmo payload:
+
+```ruby
+Person.datatable({ filters: { tag_ids: id } })                          # contém id          (tag_ids @> ARRAY[id])
+Person.datatable({ filters: [{ tag_ids: a }, { tag_ids: b }] })          # contém a OU b      (tag_ids && ARRAY[a, b])
+Person.datatable({ filters: { tag_ids: "null" } })                       # array vazio
+```
+
+Vários valores casam com **qualquer** um por padrão (como o `IN`). Para exigir **todos**:
+
+```ruby
+class Person < ApplicationRecord
+  huginn_array_match :tag_ids, :all
+  # ou, com alias:
+  huginn_attributes tags: { column: "people.tag_ids", array: :all }
+end
+```
+
+Os valores são convertidos pelo tipo do elemento (um UUID inválido é descartado, nunca vai ao banco) e o literal do array é montado só com valores escapados. Colunas array ficam fora das colunas padrão do `search`.
+
 ### Ordenação/filtro com associação
 
 Qualquer referência `column` **ou** `associacao.column` é validada e mapeada para a tabela refletida real:
@@ -189,6 +224,14 @@ Person.search("globex")                            # encontra company.name via s
 Person.search("kayky", distinct: false)            # desativa o DISTINCT implícito
 ```
 
+`searchable_columns columns: []` é respeitado: um array vazio significa "pesquisar somente as associações declaradas" — não cai mais para as colunas `:string`/`:text` do próprio modelo:
+
+```ruby
+class Person < ApplicationRecord
+  searchable_columns columns: [], company: [:name, :cnpj]  # só company.name/cnpj são pesquisados
+end
+```
+
 `Huginn::Datatable` reutiliza `Huginn::Searchable.search` automaticamente quando o modelo responde a `search`.
 
 ## Índices trigram (performance)
@@ -231,6 +274,51 @@ Observações:
 - Só ajuda em termos de busca de **3 caracteres ou mais** — trigramas precisam disso para casar. Termos menores sempre fazem scan.
 - Para conferir o uso, rode `Person.search("termo").explain` com o wrapper configurado e um índice `gin_trgm_ops` presente.
 
+## Índices full-text (performance)
+
+Sob `:full_text`, cada coluna pesquisável gera um predicado por lexema respaldado por um índice GIN tsvector:
+
+```sql
+public.f_tsvector(col) @@ plainto_tsquery('portuguese'::regconfig, 'termo')
+```
+
+Como o `to_tsvector()` é `STABLE` (não `IMMUTABLE`), ele não pode ser indexado diretamente — você precisa de um wrapper `IMMUTABLE` que fixe o dicionário além do índice de expressão:
+
+```sql
+CREATE OR REPLACE FUNCTION public.f_tsvector(text)
+RETURNS tsvector AS $$
+  SELECT to_tsvector('portuguese'::regconfig, $1);
+$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
+
+CREATE INDEX index_people_name_fts ON people USING gin (public.f_tsvector(name));
+```
+
+E aponte a gem para o wrapper e o dicionário:
+
+```ruby
+Huginn.configure do |c|
+  c.search_strategy = :full_text
+  c.fts_dictionary  = "portuguese"
+  c.fts_function    = "public.f_tsvector"
+end
+```
+
+Ou gere a migration para todos os modelos Searchable (wrapper + índices GIN inclusos), escolhendo um dicionário com `--dictionary`:
+
+```sh
+rails g huginn:fts_indexes                               # todos os modelos Searchable
+rails g huginn:fts_indexes Person Product                # modelos específicos
+rails g huginn:fts_indexes --dictionary english          # fixar outro dicionário
+```
+
+O índice é **opcional** — sem o wrapper/índice a busca degrada graciosamente para o fallback unaccent+ILIKE e permanece correta (via sequential scan).
+
+Observações:
+
+- Requer o suporte a full text search embutido no PostgreSQL (sem extensão extra).
+- `:full_text` não tem tolerância a typos — combine com `:pg_trgm` (`search_strategy: [:pg_trgm, :full_text]`) e gere **os dois** conjuntos de índices (`huginn:trigram_indexes` + `huginn:fts_indexes`).
+- Para conferir o uso, rode `Person.search("termo").explain` com o wrapper configurado e um índice GIN tsvector presente.
+
 ## Eficiência da query
 
 ```
@@ -246,7 +334,7 @@ Para um datatable de `Plano` com `includes:` profundos, isso são exatamente **2
 
 ```
 lib/huginn.rb                       entry, Huginn.configure, Huginn.instrument
-lib/huginn/configuration.rb         search_strategy, unaccent_function, pagy_*
+lib/huginn/configuration.rb         search_strategy, unaccent_function, fts_*, pagy_*
 lib/huginn/railtie.rb               auto-inclui os concerns no ActiveRecord
 lib/huginn/datatable.rb             Huginn::Datatable (agregador)
 lib/huginn/datatable/datatable.rb   o Concern do datatable
@@ -258,8 +346,8 @@ 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 (subqueries + OR)
-lib/huginn/searchable/fuzzy.rb      predicados pg_trgm / unaccent / simple
-lib/generators/...                  gerador `huginn:trigram_indexes` (migrations de índices GIN)
+lib/huginn/searchable/fuzzy.rb      predicados pg_trgm / full_text / unaccent / simple
+lib/generators/...                  geradores `huginn:trigram_indexes` + `huginn:fts_indexes` (migrations de índices GIN)
 ```
 
 ## Instrumentação

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

@@ -7,6 +7,7 @@ module Huginn
     included do
       class_attribute :huginn_attribute_mapping, default: nil
       class_attribute :huginn_strict_mapping, default: false
+      class_attribute :huginn_array_modes, default: {}
     end
 
     class_methods do
@@ -60,15 +61,49 @@ module Huginn
       # are rejected — API callers can only filter/order by the aliases.
       # Without a mapping the model falls back to plain/reflected columns.
       # Accepts a positional Hash or keyword arguments.
+      #
+      # An alias over a PostgreSQL array column may set how several filter
+      # values match (see `huginn_array_match`):
+      #
+      #   huginn_attributes tags: { column: "people.tags", array: :all }
       def huginn_attributes(mapping = nil, strict: true, **aliases)
         merged = (mapping || {}).merge(aliases)
-        self.huginn_attribute_mapping = merged.map { |key, value| [key.to_s, value.to_s] }.to_h
+        modes = {}
+        self.huginn_attribute_mapping = merged.to_h do |key, value|
+          if value.is_a?(Hash)
+            options = value.transform_keys(&:to_sym)
+            modes[key.to_s] = normalized_array_mode(options[:array]) if options.key?(:array)
+            [key.to_s, options.fetch(:column).to_s]
+          else
+            [key.to_s, value.to_s]
+          end
+        end
+        self.huginn_array_modes = huginn_array_modes.merge(modes)
         self.huginn_strict_mapping = strict
         huginn_attribute_mapping
       end
 
+      # How several values filter a PostgreSQL array column:
+      #
+      #   :any (default)  row contains at least one of the values (`&&`),
+      #                   the same semantics as `IN` on a plain column
+      #   :all            row contains every value (`@>`)
+      #
+      #   huginn_array_match :tag_ids, :all
+      def huginn_array_match(*fields, mode)
+        mode = normalized_array_mode(mode)
+        self.huginn_array_modes = huginn_array_modes.merge(fields.flatten.to_h { |field| [field.to_s, mode] })
+      end
+
       private
 
+      def normalized_array_mode(mode)
+        mode = mode.to_s.to_sym
+        raise ArgumentError, "array mode must be :any or :all, got #{mode.inspect}" unless %i[any all].include?(mode)
+
+        mode
+      end
+
       def apply_datatable_search(relation, value)
         return relation if value.blank? || !respond_to?(:search)
 
@@ -102,6 +137,7 @@ module Huginn
       def apply_plain_filter(relation, validator, values)
         attr = validator.arel_attribute
         return relation if attr.nil?
+        return relation.where(array_predicate(attr, validator, values)) if validator.array?
 
         if values.include?("null")
           apply_nullable_predicate(relation, attr, values)
@@ -119,7 +155,9 @@ module Huginn
         return relation unless subquery
 
         attr   = validator.arel_attribute
-        target = if values.include?("null")
+        target = if validator.array?
+                   subquery.where(array_predicate(attr, validator, values))
+                 elsif values.include?("null")
                    apply_nullable_predicate(subquery, attr, values)
                  elsif values.size == 1
                    subquery.where(attr.eq(values.first))
@@ -207,6 +245,35 @@ module Huginn
         nil
       end
 
+      # PostgreSQL array columns: one value means "contains it" (`@>`); several
+      # values follow the field's array mode — :any (`&&`, like IN) or :all
+      # (`@>`). "null" matches an empty (or NULL) array. Values are cast by the
+      # element type, so invalid ones are dropped before reaching SQL, and the
+      # literal is built from quoted values only.
+      def array_predicate(attr, validator, values)
+        wants_empty = values.include?("null")
+        cast = values.reject { |value| value == "null" }.filter_map { |value| validator.cast_array_element(value) }.uniq
+        predicates = []
+        predicates << empty_array_predicate(attr) if wants_empty
+        unless cast.empty?
+          operator = cast.size == 1 || validator.array_mode == :all ? "@>" : "&&"
+          predicates << Arel::Nodes::InfixOperation.new(operator, attr, array_literal(cast, validator.array_element_sql_type))
+        end
+        return Arel::Nodes::SqlLiteral.new("1=0") if predicates.empty?
+
+        predicates.reduce { |left, right| Arel::Nodes::Grouping.new(left.or(right)) }
+      end
+
+      def array_literal(values, sql_type)
+        quoted = values.map { |value| connection.quote(value) }.join(", ")
+        Arel::Nodes::SqlLiteral.new("ARRAY[#{quoted}]::#{sql_type}[]")
+      end
+
+      def empty_array_predicate(attr)
+        cardinality = Arel::Nodes::NamedFunction.new("cardinality", [attr])
+        Arel::Nodes::NamedFunction.new("COALESCE", [cardinality, Arel::Nodes.build_quoted(0)]).eq(0)
+      end
+
       def apply_nullable_predicate(relation, attr, values)
         non_null = values.reject { |value| value == "null" }
         predicate = if non_null.empty?

data/lib/huginn/datatable/filter_normalizer.rb

@@ -6,8 +6,9 @@ module Huginn
     # (ActionController::Parameters, Hash, Array of hashes, [key, value]
     # pairs, ...) into a single Hash of { column => Array(values) }.
     #
-    # Values are accumulated in arrays so that repeated keys produce an
-    # IN condition when applied as a datatable filter. Invalid payload
+    # Values are accumulated in arrays so that repeated keys — or a key with
+    # an Array of values — produce an IN condition when applied as a
+    # datatable filter. Invalid payload
     # shapes are simply ignored, and keys are normalized to strings.
     class FilterNormalizer
       def self.call(raw)
@@ -20,7 +21,9 @@ module Huginn
 
       def call
         each_pair(@raw).each_with_object({}) do |(key, value), acc|
-          (acc[key.to_s] ||= []) << value
+          # { "col" => [a, b] } (e.g. filters[col][]=a&filters[col][]=b) is the
+          # same as repeating the key: several values, IN / array match.
+          (acc[key.to_s] ||= []).concat(value.is_a?(Array) ? value : [value])
         end
       end
 

data/lib/huginn/datatable/validator.rb

@@ -24,6 +24,7 @@ module Huginn
 
       def initialize(model, field)
         @model = model
+        @public_name = field.to_s
         @strict_denied = false
         @field = resolve_alias(field)
         @field = @field.split(".").drop(1).join(".") if own_table_prefix?(@field)
@@ -74,6 +75,35 @@ module Huginn
         klass.columns_hash[column].type
       end
 
+      # True for PostgreSQL array columns (e.g. `uuid[]`, `text[]`).
+      def array?
+        definition = column_definition
+        !!(definition.respond_to?(:array?) ? definition.array? : definition&.try(:array))
+      end
+
+      # SQL type of the array elements ("uuid", "character varying"...),
+      # used to cast the filter literal.
+      def array_element_sql_type
+        column_definition.sql_type.delete_suffix("[]")
+      end
+
+      # Casts a filter value with the array element type; nil when invalid.
+      def cast_array_element(value)
+        type = target_klass.type_for_attribute(column)
+        element = type.respond_to?(:subtype) ? type.subtype : type
+        element.serialize(element.cast(value))
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # :any or :all, declared with huginn_attributes(array:) or
+      # huginn_array_match (by public alias or by column name).
+      def array_mode
+        modes = target_klass.respond_to?(:huginn_array_modes) ? target_klass.huginn_array_modes : {}
+        own = model.respond_to?(:huginn_array_modes) ? model.huginn_array_modes : {}
+        own[@public_name] || own[@field] || modes[column] || :any
+      end
+
       # The AssociationPath for scoped fields (builds filter/order
       # subqueries), or nil for plain columns.
       def association_path
@@ -111,6 +141,16 @@ module Huginn
         segments.size >= 2 && segments.first == model.table_name
       end
 
+      def target_klass
+        plain? ? model : association_path.target_klass
+      end
+
+      def column_definition
+        return nil unless valid?
+
+        target_klass.columns_hash[column]
+      end
+
       def strict_denied?
         @strict_denied
       end

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,18 +36,23 @@ 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
 
       def default_searchable_columns
         columns_hash.each_with_object([]) do |(name, column), acc|
-          acc << name if %i[string text].include?(column.type)
+          # Array columns (string[]/text[]) are not searchable text: unaccent/ILIKE need a scalar.
+          acc << name if %i[string text].include?(column.type) && !column.try(:array)
         end
       end
     end

data/lib/huginn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Huginn
-  VERSION = "0.2.1"
+  VERSION = "0.4.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.4.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
@@ -178,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Performant and elegant ActiveRecord datatables/data-grids with tolerant search
 test_files: []