Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
O tipo de coluna JSON nativo do MySQL valida o JSON na inserção, o armazena em um formato binário para acesso eficiente e fornece um conjunto de funções para ler e modificar campos individuais sem analisar o documento inteiro.

Armazenando JSON

O MySQL valida o JSON na inserção. Inserir JSON malformado gera um erro.

Lendo Campos JSON

Use JSON_EXTRACT(column, path) ou a abreviação ->:
Ambos retornam um valor JSON — a string "Acme" com aspas. Para obter uma string simples sem aspas, use ->> (que é a abreviação de JSON_UNQUOTE(JSON_EXTRACT(...))):
Sintaxe de caminho:
  • $.key — acessa um campo de objeto
  • $.array[0] — acessa um elemento de array pelo índice
  • $.array[*] — todos os elementos de um array
  • $.** — curinga recursivo (todos os valores em qualquer profundidade)

Filtrando por Campos JSON

Observe que ->> retorna uma string, então comparar com '16' (e não 16) é o correto, a menos que você faça a conversão explicitamente: CAST(attributes ->> '$.ram_gb' AS UNSIGNED).

Modificando JSON

As funções principais:

Indexando Campos JSON

A coluna JSON em si não pode ser indexada diretamente. Para indexar um campo JSON específico, crie uma coluna gerada e indexe essa coluna:
Agora WHERE attributes ->> '$.brand' = 'Acme' pode usar idx_brand. O MySQL reconhece que a expressão da coluna gerada corresponde à condição da consulta. Isso é tratado com mais detalhes em Escolhendo Tipos de Dados no MySQL — é o padrão recomendado sempre que você consulta um campo JSON com frequência suficiente para precisar de um índice.

JSON vs Colunas Normalizadas

Use JSON quando a estrutura é genuinamente variável (atributos configuráveis pelo usuário, metadados de eventos, payloads de APIs de terceiros). Use colunas normalizadas quando a estrutura é fixa e você precisa filtrar, juntar ou agregar pelos campos.

Perguntas Frequentes

Posso indexar um array JSON para consultas de contenção?

Não diretamente com um índice padrão. Para consultas JSON_CONTAINS, a única opção é uma varredura completa da tabela, a menos que você extraia o array para uma tabela filha separada (normalizada) ou use um índice full-text em uma coluna gerada que achata o array. Para consultas de contenção de alto volume, a normalização é o melhor caminho.

Qual é a diferença entre -> e ->>?

-> retorna um valor JSON (as strings incluem as aspas ao redor). ->> retorna a string sem aspas. Para exibição, concatenação e qualquer coisa que consuma o texto, ->> é o que você quer. A igualdade ainda funciona com ->, porém: o MySQL converte o outro operando para JSON primeiro, então attributes -> '$.brand' = 'Acme' corresponde.

Armazenar JSON prejudica o desempenho?

Ler um único campo de um documento JSON grande exige analisar a estrutura binária, o que é mais rápido do que analisar texto, mas mais lento do que ler uma coluna nativa. Para campos acessados com frequência, o padrão coluna gerada + índice coloca o desempenho de leitura no mesmo nível das colunas nativas.

Solução de Problemas

Veja também