MariaDB e JSON: Tutorial para usar JSON no MariaDB

Desde a versão 10.2, você pode usar o JSON no MariaDB para armazenar e processar informações semiestruturadas diretamente em tabelas relacionais. Mostramos as funções e os passos mais importantes.

Principais funções do JSON no MariaDB

O MariaDB oferece uma série de funções úteis que permitem trabalhar de forma eficaz com dados JSON diretamente no banco de dados. Você não precisa de um banco NoSQL adicional. Com os seguintes recursos, é possível acessar informações específicas, modificar conteúdo ou validar dados estruturados:

• JSON_VALUE(json_doc, json_path): Permite extrair um valor específico de um campo JSON. Basta indicar o documento JSON e o caminho do elemento desejado. O MariaDB retorna exatamente esse valor, poupando o esforço de analisar o documento completo.
• JSON_SET(json_doc, path, value): Permite alterar um valor existente ou adicionar um novo campo diretamente no banco. Se o caminho existir, o valor será substituído; se não, o caminho será criado.
• JSON_REMOVE(json_doc, path): Ideal para limpar um documento JSON. Por exemplo, para remover um atributo desatualizado, basta informar o caminho correspondente.
• JSON_CONTAINS(json_doc, value, path): Útil para verificações ou filtros. Essa função permite saber se um determinado valor existe no JSON.
• JSON_VALID(json_doc): Garante que o JSON seja válido antes de processá-lo. Com essa função, o MariaDB detecta se o texto JSON está bem formatado, facilitando a identificação de erros de entrada.

Passo a passo: Usar JSON no MariaDB

Nesta seção, mostramos como armazenar, consultar e manipular dados JSON no MariaDB.

Passo 1: Criar tabela com campo JSON

Primeiro, crie uma tabela com uma coluna do tipo LONGTEXT ou JSON. O MariaDB armazena o formato JSON internamente como texto, mas verifica automaticamente a sintaxe ao utilizar funções JSON (JSON functions).

CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255),
    properties JSON
);

Na coluna properties, você pode armazenar quaisquer objetos JSON (JSON objects).

Passo 2: Inserir dados JSON

Agora você pode inserir registros com JSON válido usando MariaDB INSERT INTO:

INSERT INTO products (name, properties) VALUES (
    'desk',
    '{"color": "brown", "material": "timber", "weight": 12.5}'
);

Importante: a string JSON deve estar corretamente formatada e entre aspas. Dentro da string, aspas duplas precisam ser escapadas com uma barra invertida (\").

Passo 3: Ler dados de uma coluna JSON

Para extrair valores específicos de um objeto JSON, use JSON_VALUE():

SELECT name, JSON_VALUE(properties, '$.material') AS material
FROM products;

O resultado exibe o nome do produto e o material armazenado no campo JSON.

Passo 4: Atualizar dados JSON no MariaDB

Para alterar um valor dentro de um objeto JSON no MariaDB, utilize JSON_SET():

UPDATE products
SET properties = JSON_SET(properties, '$.color', 'white')
WHERE name = 'desk';

Você também pode adicionar novos pares chave-valor que ainda não existiam.

Passo 5: Remover elemento com JSON

Com JSON_REMOVE(), você pode remover valores específicos de um objeto:

UPDATE products
SET properties = JSON_REMOVE(properties, '$.weight')
WHERE name = 'desk';

Passo 6: Buscar valores dentro do JSON

No MariaDB, é possível filtrar registros com base em conteúdos específicos do JSON:

SELECT * FROM products
WHERE JSON_VALUE(properties, '$.material') = 'timber';

Isso é especialmente útil para filtros complexos, como buscas por produtos ou conteúdos personalizados.

Passo 7: Validação e depuração

Se quiser verificar se uma coluna contém JSON válido, use JSON_VALID():

SELECT name, JSON_VALID(properties) FROM products;

Um valor de retorno igual a “1” indica que o JSON é válido, enquanto “0” aponta erros de sintaxe.

Passo 8: Combinar colunas JSON com colunas geradas e índices

Como o MariaDB armazena dados JSON internamente como texto, ele precisa interpretar os dados a cada consulta. Isso pode causar problemas de desempenho, especialmente em tabelas grandes ou com acessos frequentes a campos JSON específicos. Uma solução eficiente são as colunas geradas, que extraem valores do JSON e os armazenam separadamente.

Por exemplo, você pode extrair o valor da chave material da coluna properties e armazená-lo em uma nova coluna indexável:

ALTER TABLE products
ADD COLUMN material VARCHAR(100) AS (JSON_VALUE(properties, '$.material')) STORED,
ADD INDEX idx_material (material);

Esse comando cria a coluna material, que armazena o valor extraído de $.material. A palavra-chave STORED garante que o valor seja fisicamente salvo no banco de dados (e não apenas calculado em tempo de execução). Além disso, o índice idx_material permite buscas mais rápidas.

Depois disso, você poderá executar consultas com muito mais eficiência:

SELECT name FROM products WHERE material = 'timber';

Principalmente em ambientes de produção com muitos acessos de leitura, essa técnica vale a pena. Ela reduz a carga de processamento durante as consultas e garante tempos de resposta mais curtos mesmo com grandes volumes de dados.

Por que a combinação MariaDB e JSON é vantajosa?

O uso de JSON no MariaDB é especialmente útil quando as aplicações precisam armazenar dados em uma estrutura variável. Isso inclui configurações, respostas de APIs, perfis de usuários ou registros de log. O JSON permite guardar conteúdos aninhados e flexíveis diretamente em uma única coluna. Assim, não é necessário criar colunas adicionais para cada possível campo. Em vez disso, você simplesmente insere os novos valores diretamente na estrutura JSON. Isso permite ajustar os dados sem alterar o esquema do banco.

Especialmente em sistemas que exigem tanto estruturas de tabela fixas quanto armazenamento de dados flexível, o MariaDB JSON oferece uma solução rápida e prática. Você trabalha com conteúdo dinâmico sem renunciar às vantagens das consultas SQL tradicionais. Dessa forma, combina-se a estabilidade dos dados relacionais com a flexibilidade dos bancos NoSQL.