Como o JSONB funciona e quando você deve usá-lo?

Question

Accepted Answer

**`JSONB`** é o tipo JSON binário do PostgreSQL — ele armazena dados JSON em um formato eficiente, **consultável e indexável**. Permite armazenar dados flexíveis e semi-estruturados em um banco de dados relacional, combinando integridade relacional com flexibilidade similar à NoSQL. É um dos recursos mais poderosos do Postgres.

## JSONB vs JSON

```text
JSON  → stores the exact text (preserves whitespace/key order/duplicates), parsed each query
JSONB → stores a DECOMPOSED BINARY format → slightly slower to write, but MUCH faster
        to query, and supports INDEXING and rich operators
→ Use JSONB in almost all cases (JSON only if you need exact text preservation).
```

## Armazenando e consultando JSONB

```sql
CREATE TABLE products (id SERIAL, attributes JSONB);
INSERT INTO products (attributes) VALUES
  ('{"color": "red", "size": "L", "tags": ["new", "sale"]}');

-- extract values
SELECT attributes->'color'   FROM products;   -- -> returns JSONB: "red"
SELECT attributes->>'color'  FROM products;   -- ->> returns TEXT: red
SELECT attributes#>>'{tags,0}' FROM products; -- nested path: first tag

-- query by content
SELECT * FROM products WHERE attributes->>'color' = 'red';
SELECT * FROM products WHERE attributes @> '{"color": "red"}';  -- containment
SELECT * FROM products WHERE attributes ? 'color';              -- key exists
```

Operadores: `->` (obter campo JSONB), `->>` (obter como texto), `@>` (contenção), `?` (chave existe), `#>>` (caminho aninhado). Esses operadores tornam JSONB ricamente consultável — ao contrário de armazenar JSON como texto simples.

## Indexando JSONB (essencial para desempenho)

```sql
-- a GIN index makes containment/key queries fast
CREATE INDEX idx_attrs ON products USING GIN (attributes);
-- now WHERE attributes @> '{"color": "red"}' uses the index

-- or index a specific extracted field
CREATE INDEX idx_color ON products ((attributes->>'color'));
```

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

```text
✓ USE for: flexible/variable attributes, settings, API payloads, sparse fields,
  semi-structured data that varies per row, or rapidly-evolving schemas
✗ AVOID for: data that's well-structured and queried relationally → use normal columns
  (better constraints, types, and typically better performance for structured queries)
→ Mix both: structured data in columns, variable/flexible data in a JSONB column.
```

## Por que isso importa

JSONB é um dos recursos mais importantes e distintivos do PostgreSQL, e entendê-lo é altamente valioso porque permite **armazenar e consultar eficientemente dados semi-estruturados dentro de um banco de dados relacional** — combinando a integridade, transações e poder relacional do Postgres com a flexibilidade de um armazenamento de documentos/NoSQL, o que é uma capacidade importante para aplicações modernas.

A vantagem-chave em relação ao armazenamento de JSON como texto simples (ou tipo `JSON`) é que **JSONB é consultável e indexável**: operadores ricos (`->`, `->>`, `@>`, `?`) permitem extrair e filtrar conteúdo JSON, e **índices GIN** (ou índices em campos extraídos) tornam essas consultas rápidas — assim você obtém flexibilidade similar à de armazenamentos de documentos sem sacrificar o desempenho de consultas.

Isso torna JSONB ideal para atributos flexíveis ou variáveis, configurações, cargas úteis de API, dados esparsos e esquemas em evolução — necessidades comuns em aplicações modernas que de outra forma exigiriam um banco de dados NoSQL ou designs de esquema inadequados.

Compreender a distinção **JSONB vs JSON** (JSONB para quase todos os casos), os operadores de consulta, **indexação** (essencial para desempenho) e crucialmente **quando usar JSONB versus colunas normais** (JSONB para dados flexíveis/variáveis/semi-estruturados, colunas normais para dados bem-estruturados consultados relacionalmente — frequentemente misturando ambos) reflete julgamento de design maduro.

Como a capacidade de lidar com dados flexíveis e semi-estruturados é cada vez mais importante, e como JSONB fornece isso dentro de um banco de dados relacional robusto (frequentemente eliminando a necessidade de um armazenamento NoSQL separado), entender JSONB — suas consultas, indexação e uso apropriado — é conhecimento valioso, frequentemente relevante, que é uma razão essencial pela qual PostgreSQL é tão popular para aplicações modernas e uma marca registrada de aproveitar todo o poder do Postgres.