Como funcionam as colunas de array no PostgreSQL?

Question

Accepted Answer

PostgreSQL suporta colunas de **array** — uma única coluna pode conter *múltiplos valores* do mesmo tipo. Esta é uma característica distintiva do Postgres útil para armazenar listas (tags, roles, scores) sem uma tabela separada, com operadores e funções para consultar.

## Definindo e inserindo arrays

```sql
CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  title TEXT,
  tags TEXT[]                         -- an array of text
);

INSERT INTO posts (title, tags) VALUES
  ('Hello', ARRAY['ruby', 'web']),    -- ARRAY[] syntax
  ('World', '{"news", "tech"}');       -- or curly-brace literal
```

A sintaxe `type[]` declara uma coluna de array. Você insere com a sintaxe literal `ARRAY[...]` ou `'{...}'`.

## Consultando arrays

```sql
-- ANY — does the array contain a value?
SELECT * FROM posts WHERE 'ruby' = ANY(tags);

-- @> containment — does the array contain ALL of these?
SELECT * FROM posts WHERE tags @> ARRAY['ruby', 'web'];

-- && overlap — do the arrays share ANY element?
SELECT * FROM posts WHERE tags && ARRAY['tech', 'news'];

-- access by index (1-based!) and length
SELECT tags[1], array_length(tags, 1) FROM posts;

-- unnest — expand an array into rows
SELECT id, unnest(tags) AS tag FROM posts;   -- one row per tag
```

Operadores como `ANY` (contém um valor), `@>` (contenção) e `&&` (sobreposição), além de funções como `unnest` (expandir em linhas) e `array_agg` (agregar linhas em um array), tornam os arrays consultáveis.

## Indexando arrays (GIN)

```sql
-- a GIN index makes array containment/membership queries fast
CREATE INDEX idx_posts_tags ON posts USING GIN (tags);
-- now WHERE tags @> ARRAY['ruby'] uses the index
```

## Quando usar arrays (e quando não)

```text
✓ USE for: simple lists tightly coupled to the row (tags, roles, a few scores)
  where you don't need to query/join the individual values much
✗ AVOID when: you need to query, join, or maintain the values relationally,
  or the list is large/complex → a separate related table (normalized) is better
→ Arrays are convenient but can violate normalization; use them judiciously.
```

## Por que isso importa

Colunas de array são uma característica distintiva e útil do PostgreSQL, e entendê-las é valioso tanto para aproveitar os recursos do Postgres quanto para tomar decisões de design fundamentadas.

Arrays permitem que você armazene **múltiplos valores em uma única coluna** (tags, roles, listas) sem uma tabela separada — conveniente para listas simples fortemente acopladas a uma linha.

Compreender como definir, inserir e especialmente **consultar** arrays (operadores como `ANY` para pertencimento, `@>` para contenção, `&&` para sobreposição, e funções como `unnest` para expandir arrays em linhas) é necessário para usá-los efetivamente, e saber que **índices GIN** tornam as consultas de arrays eficientes é importante para o desempenho.

Igualmente importante é o **julgamento de design** de quando usar arrays versus uma tabela relacionada normalizada: arrays são convenientes para listas simples que você não precisa consultar, juntar ou manter relacionalmente, mas podem violar princípios de normalização e se tornar difíceis quando você precisa consultar valores individuais, fazer junções com eles ou gerenciar uma lista complexa/grande — neste caso, uma tabela relacionada separada é a melhor escolha normalizada.

Compreender este trade-off (arrays para conveniência com listas simples acopladas, tabelas separadas para dados gerenciados relacionalmente) reflete um julgamento de design fundamentado.

Já que arrays são uma característica útil e distintiva do Postgres que pode simplificar certos designs (evitando uma tabela de junção para listas simples) mas podem ser mal utilizados (desnormalizando dados que deveriam ser relacionais), compreender colunas de array — como defini-las, consultá-las e indexá-las, e crucialmente quando são apropriadas versus quando uma tabela normalizada é melhor — é conhecimento valioso e praticamente relevante para projetar esquemas Postgres que usem a abordagem correta para cada tipo de dados com múltiplos valores.