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 in­for­ma­ções se­mi­es­tru­tu­ra­das di­re­ta­mente em tabelas re­la­ci­o­nais. Mostramos as funções e os passos mais im­por­tan­tes.

Prin­ci­pais 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 di­re­ta­mente no banco de dados. Você não precisa de um banco NoSQL adicional. Com os seguintes recursos, é possível acessar in­for­ma­ções es­pe­cí­fi­cas, modificar conteúdo ou validar dados es­tru­tu­ra­dos:

• JSON_VALUE(json_doc, json_path): Permite extrair um valor es­pe­cí­fico de um campo JSON. Basta indicar o documento JSON e o caminho do elemento desejado. O MariaDB retorna exa­ta­mente 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 di­re­ta­mente no banco. Se o caminho existir, o valor será subs­ti­tuí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 de­sa­tu­a­li­zado, basta informar o caminho cor­res­pon­dente.
• JSON_CONTAINS(json_doc, value, path): Útil para ve­ri­fi­ca­ções ou filtros. Essa função permite saber se um de­ter­mi­nado 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, fa­ci­li­tando a iden­ti­fi­ca­çã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 in­ter­na­mente como texto, mas verifica au­to­ma­ti­ca­mente 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}'
);

Im­por­tante: a string JSON deve estar cor­re­ta­mente 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 es­pe­cí­fi­cos 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 ar­ma­ze­nado 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 es­pe­cí­fi­cos 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 es­pe­cí­fi­cos do JSON:

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

Isso é es­pe­ci­al­mente útil para filtros complexos, como buscas por produtos ou conteúdos per­so­na­li­za­dos.

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 in­ter­na­mente como texto, ele precisa in­ter­pre­tar os dados a cada consulta. Isso pode causar problemas de de­sem­pe­nho, es­pe­ci­al­mente em tabelas grandes ou com acessos fre­quen­tes a campos JSON es­pe­cí­fi­cos. Uma solução eficiente são as colunas geradas, que extraem valores do JSON e os armazenam se­pa­ra­da­mente.

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 fi­si­ca­mente 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 efi­ci­ên­cia:

SELECT name FROM products WHERE material = 'timber';

Prin­ci­pal­mente em ambientes de produção com muitos acessos de leitura, essa técnica vale a pena. Ela reduz a carga de pro­ces­sa­mento durante as consultas e garante tempos de resposta mais curtos mesmo com grandes volumes de dados.

Por que a com­bi­na­ção MariaDB e JSON é vantajosa?

O uso de JSON no MariaDB é es­pe­ci­al­mente útil quando as apli­ca­ções precisam armazenar dados em uma estrutura variável. Isso inclui con­fi­gu­ra­ções, respostas de APIs, perfis de usuários ou registros de log. O JSON permite guardar conteúdos aninhados e flexíveis di­re­ta­mente em uma única coluna. Assim, não é ne­ces­sá­rio criar colunas adi­ci­o­nais para cada possível campo. Em vez disso, você sim­ples­mente insere os novos valores di­re­ta­mente na estrutura JSON. Isso permite ajustar os dados sem alterar o esquema do banco.

Es­pe­ci­al­mente em sistemas que exigem tanto es­tru­tu­ras de tabela fixas quanto ar­ma­ze­na­mento 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 tra­di­ci­o­nais. Dessa forma, combina-se a es­ta­bi­li­dade dos dados re­la­ci­o­nais com a fle­xi­bi­li­dade dos bancos NoSQL.