Domine as funções JSONB no PostgreSQL: um guia prático

O tipo de dado JSONB do PostgreSQL facilita o tratamento de dados JSON no seu banco de dados. Seus recursos vão além do simples armazenamento, oferecendo funções sofisticadas que permitem manipular e consultar dados JSON em detalhes. Este guia explora essas funções JSONB com exemplos práticos para ajudar você a aproveitar o poder do PostgreSQL no gerenciamento de dados JSON.

Para uma visão mais ampla de como trabalhar com JSON no PostgreSQL, incluindo os tipos json e jsonb, confira nosso guia completo de funções JSON do PostgreSQL.

Introdução ao JSONB

O tipo de dado jsonb no PostgreSQL é um formato binário que armazena dados JSON. Ele é altamente eficiente e oferece recursos de indexação que o json não tem. Em geral, o JSONB é preferível pela sua flexibilidade e pelos ganhos de desempenho.

Criando uma tabela com JSONB

Vamos começar criando uma tabela que usa o tipo de dado jsonb:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    data JSONB
);

Inserindo dados JSONB

Insira dados JSONB usando a sintaxe JSON padrão. O PostgreSQL valida e converte automaticamente o JSON para o formato binário:

INSERT INTO users (data) VALUES 
('{"name": "John Doe", "email": "john@example.com", "age": 30}'),
('{"name": "Jane Doe", "email": "jane@example.com", "age": 25}'),
('{"name": "Alice Smith", "email": "alice@example.com", "age": 28, "address": {"city": "New York", "state": "NY"}}');

Acessando valores JSONB

O PostgreSQL oferece vários operadores para explorar valores JSONB.

Extraindo um objeto JSONB

Para acessar valores JSONB aninhados, use os operadores -> e ->>. O operador -> retorna os dados em formato JSON, enquanto ->> retorna texto.

SELECT data->'name' AS name, data->>'email' AS email FROM users;

Saída esperada:

  name   |       email        
---------+--------------------
 "John Doe" | john@example.com
 "Jane Doe" | jane@example.com

Extraindo valores JSONB aninhados

Para estruturas JSON mais profundas, encadeie os operadores. O operador ? verifica primeiro se a chave existe:

SELECT 
    data->>'name' AS name,
    data->'address'->>'city' AS city 
FROM users 
WHERE data ? 'address';

Saída esperada:

    name     |   city   
-------------|----------
 Alice Smith | New York

Funções JSONB

O PostgreSQL inclui um conjunto de funções JSONB que vão além da simples extração de valores.

Verificando a existência de uma chave

O operador ? verifica se uma chave existe:

SELECT data ? 'age' AS has_age FROM users;

Saída esperada:

 has_age 
---------
 t
 t
 t

Verificando contenção

Use o operador @> para verificar se um objeto JSON contém outro:

SELECT * FROM users WHERE data @> '{"age": 30}';

Saída esperada:

 id |                    data                     
----+---------------------------------------------
  1 | {"name": "John Doe", "email": "john@example.com", "age": 30}

Concatenação de JSONB

Combine colunas ou valores JSONB usando o operador ||:

SELECT data || '{"verified": false}' AS updated_data FROM users;

Saída esperada:

                            updated_data                            
-------------------------------------------------------------------
 {"age": 30, "name": "John Doe", "email": "john@example.com", "verified": false}
 {"age": 25, "name": "Jane Doe", "email": "jane@example.com", "verified": false}
 {"age": 28, "name": "Alice Smith", "email": "alice@example.com", "address": {"city": "New York", "state": "NY"}, "verified": false}

Removendo uma chave do JSONB

Remova uma chave usando o operador -:

SELECT data - 'age' AS partial_data FROM users;

Saída esperada:

                            partial_data                             
--------------------------------------------------------------------
 {"name": "John Doe", "email": "john@example.com"}
 {"name": "Jane Doe", "email": "jane@example.com"}
 {"name": "Alice Smith", "email": "alice@example.com", "address": {"city": "New York", "state": "NY"}}

Indexação de JSONB

Para melhorar o desempenho de consultas em dados JSONB, use índices.

Criando um índice JSONB

Um índice GIN é ideal para tipos JSONB:

CREATE INDEX idx_users_data ON users USING GIN (data);

Esse índice ajuda a acelerar operações como buscar a existência de chaves JSON ou de pares chave-valor.

Funções JSONB avançadas

O PostgreSQL oferece funções adicionais para operações mais complexas:

-- Convert JSONB to key-value pairs
SELECT jsonb_each_text(data) FROM users LIMIT 1;

-- Get all keys from a JSONB object
SELECT jsonb_object_keys(data) FROM users LIMIT 1;

-- Update a nested value using jsonb_set
UPDATE users 
SET data = jsonb_set(data, '{address,zip}', '"10001"')
WHERE data ? 'address';

Conclusão

As funções JSONB do PostgreSQL oferecem opções poderosas e flexíveis para trabalhar com dados JSON no seu banco de dados. As principais vantagens incluem:

• Desempenho: formato de armazenamento binário com indexação eficiente
• Operadores completos: extração e manipulação fáceis com ->, ->>, @>, ?
• Funções avançadas: operações complexas como jsonb_set, jsonb_each_text e jsonb_array_elements
• Suporte a indexação: índices GIN para consultas rápidas

Esses recursos tornam o PostgreSQL uma excelente escolha para aplicações que precisam armazenar e consultar dados JSON semiestruturados junto com dados relacionais tradicionais. Ao dominar essas funções JSONB, você pode criar aplicações de banco de dados mais flexíveis e eficientes.