SQL Academy · Aula

Indexação de JSONB com GIN

Crie índices GIN em documentos JSONB e use jsonb_path_ops para obter consultas de contenção rápidas.

Indexação de JSONB com GIN é uma aula grátis de SQL Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de SQL Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de SQL Academy inclui 4 aulas no total.

Por que usar GIN para JSONB

Os documentos JSONB têm muitos "itens" (pares chave/valor e elementos de matrizes). O GIN (índice invertido generalizado) foi criado para consultas do tipo "linhas cujo documento contém X".

Índice GIN padrão

A classe de operadores padrão oferece suporte a @>, ?, ?| e ?&:

CREATE INDEX events_data_gin ON events USING GIN (data);

-- These now use the index:
SELECT * FROM events WHERE data @> '{"type":"login"}';
SELECT * FROM events WHERE data ? 'error';

jsonb_path_ops: menor e mais rápido

Tem metade do tamanho e é mais rápido para consultas que usam apenas contenção, mas oferece suporte ONLY a @>:

CREATE INDEX events_data_gin ON events USING GIN (data jsonb_path_ops);

-- Supports @>
-- Does NOT support ?  ?|  ?&
SELECT * FROM events WHERE data @> '{"type":"login"}';

Indexe apenas um caminho

Se você consulta apenas uma chave, um índice B-tree de expressão sobre o valor extraído é ainda mais rápido:

CREATE INDEX events_user_id_idx
  ON events (((data->>'user_id')::BIGINT));

SELECT * FROM events WHERE (data->>'user_id')::BIGINT = 42;

Indexação dentro de matrizes

Use um índice GIN no caminho da matriz:

CREATE INDEX events_tags_gin
  ON events USING GIN ((data->'tags'));

SELECT * FROM events WHERE data->'tags' @> '["admin"]'::JSONB;

Combinação do índice JSONB com outros filtros

Predicados compostos podem usar o índice GIN para a parte JSONB e outro índice para a parte que não é JSONB:

EXPLAIN ANALYZE
SELECT * FROM events
WHERE data @> '{"type":"login"}'
  AND ts >= NOW() - INTERVAL '7 days';
-- BitmapAnd: GIN index on data, B-tree on ts

Desempenho de escrita do GIN

As atualizações do GIN são mais pesadas que as do B-tree. Para tabelas com muitas escritas, a opção fastupdate agrupa as atualizações do GIN em uma lista pendente, que é limpa pelo VACUUM.

CREATE INDEX events_data_gin ON events USING GIN (data) WITH (fastupdate = on);

-- Flush manually if needed:
SELECT gin_clean_pending_list('events_data_gin');

Tamanho do índice

Os índices GIN de JSONB podem ser grandes. Para tabelas enormes, considere:

Indexar apenas caminhos específicos (índice de expressão)
Mudar para jsonb_path_ops quando só houver consultas de contenção
Separar os campos mais acessados em colunas reais

Combinação com trigramas

Para pesquisas de texto aproximadas dentro do JSONB, extraia o valor para uma expressão TEXT e adicione um índice GIN de pg_trgm:

CREATE INDEX events_message_trgm
  ON events USING GIN ((data->>'message') gin_trgm_ops);

Quando a indexação não ajuda

Se o filtro abranger todas as linhas (seletividade muito baixa), o planejador poderá escolher uma varredura sequencial mesmo com o índice. Use EXPLAIN ANALYZE para confirmar.

Manutenção dos índices JSONB

Os índices GIN sofrem inchaço como qualquer outro índice. Use REINDEX CONCURRENTLY periodicamente:

REINDEX INDEX CONCURRENTLY events_data_gin;

Recapitulação

O GIN transforma filtros JSONB em buscas que levam milissegundos.

GIN padrão: @>, ?, ?|, ?&
jsonb_path_ops: menor e exclusivo para contenção
B-tree de expressão em um escalar extraído: mais rápido para uma única chave

Verificação rápida

Você só faz consultas data @> ... em uma coluna JSONB. Qual índice oferece o menor tamanho com suporte completo aos recursos?

Perguntas Frequentes

A aula “Indexação de JSONB com GIN” é grátis?

Sim — o texto completo de “Indexação de JSONB com GIN” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de SQL Academy, atualize para CoddyKit PRO. O curso de SQL Academy inclui 4 aulas no total.

O que vou aprender em “Indexação de JSONB com GIN”?

Crie índices GIN em documentos JSONB e use jsonb_path_ops para obter consultas de contenção rápidas. Você pratica SQL Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar SQL Academy?

Nenhuma experiência prévia é necessária. SQL Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Indexação de JSONB com GIN”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de SQL Academy?

Sim. Cada aula de SQL Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

JSONB vs JSON: quando usar cada um
Operadores de caminho: -> ->> @>
Indexação de JSONB com GIN
Modelagem: quando JSONB supera a normalização

← Voltar para SQL Academy