huginn_datatable 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e68c742da97818c79b41681099972a3e4c3cc4613b8500831226abe09b2a87ed
-  data.tar.gz: 855168e5b6bbc9df1bceb381484bf20f550fcf57c0d0a35d6aba15c50b20a775
+  metadata.gz: 82a13098551b25e1b656beb853926f7dcbc964c420a64dde0e22182f735a02bb
+  data.tar.gz: abdcf5e8f489ad2b6bff0870bde97d443247f6d31b0efc93274a47da81837916
 SHA512:
-  metadata.gz: f345b93074fec47d95589bdc06078b5c2585a79e0fd2a7c02c519d3ca35baa286a885f94278a64048004891a139f4c97a293848cf094523cbcff85ccc2276ce5
-  data.tar.gz: d2bfa72d92cc096dba420c20e2a9bc0b26f466e0b981b5d9e653d6f5f2dc33c105c5fd12a1c3e3269691ecafd0704efabaec80943f166b610798066420c3fd81
+  metadata.gz: 3a03a5dc06c8f00d4a66a9bd9af8d06ddc2a9a910dbbb5c8a392985f4b0a21a89439d40829d20559232e1a04d2978444fdcf1c39ac86ce20c176af3fbb98a1de
+  data.tar.gz: b229398a323d43253aba96f667ca27dc5d76eacdf3bec68d84cb51c482e8838914de5289fdc9093a293016743f5e14c69acdc5b60705ba9e57306d639b86ca74

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ### 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.

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
@@ -120,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)
 ```
 
@@ -130,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:
@@ -202,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)
@@ -244,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
 
 ```
@@ -259,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
@@ -271,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
@@ -120,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)
 ```
 
@@ -130,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:
@@ -202,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)
@@ -244,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
 
 ```
@@ -259,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
@@ -271,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/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/searchable.rb

@@ -51,7 +51,8 @@ module Huginn
 
       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.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: huginn_datatable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kayky Marcelo
@@ -181,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: []