No MySQL, o
JSON_VALUE()
A função extrai um valor de um documento JSON no caminho especificado. A função foi introduzida no MySQL 8.0.21.
Sintaxe
A sintaxe fica assim:
JSON_VALUE(json_doc, path [RETURNING type] [on_empty] [on_error])
Onde:
on_empty:
{NULL | ERROR | DEFAULT value} ON EMPTY
on_error:
{NULL | ERROR | DEFAULT value} ON ERROR
Exemplo
Aqui está um exemplo simples para demonstrar:
SELECT JSON_VALUE( '{ "name" : "Wag", "type" : "Dog" }', '$.type' );
Resultado:
Dog
Matrizes
Aqui está um exemplo de como obter um valor de um array:
SELECT JSON_VALUE( '{ "name" : "Wag", "scores" : [ 25, 36, 48 ] }', '$.scores[1]' );
Resultado:
36
Arrays são baseados em zero, então
1
retorna o segundo elemento (0
retornaria o primeiro). Documentos incorporados
Aqui está um exemplo de como obter um valor de um objeto incorporado:
SELECT JSON_VALUE(
'{
"_id" : 1,
"details" : {
"name" : "Wag",
"type" : "Dog"
}
}',
'$.details.type'
);
Resultado:
Dog
Tipo de retorno
Aqui está um exemplo de especificação do tipo de retorno:
SELECT JSON_VALUE(
'{
"_id" : 1,
"details" : {
"name" : "Wag",
"type" : "Dog"
}
}',
'$.details' RETURNING json
);
Resultado:
{"name": "Wag", "type": "Dog"}
Se você não especificar o tipo de retorno, o tipo de retorno será
VARCHAR(512)
. Resultados vazios
Por padrão, se nenhum dado for encontrado no caminho especificado,
NULL
é retornado:SELECT JSON_VALUE(
'{
"name" : "Wag",
"type" : "Dog"
}',
'$.score'
);
Resultado:
NULL
No entanto, as opções a seguir podem ser usadas para especificar explicitamente o que deve acontecer quando nenhum dado for encontrado no caminho fornecido:
NULL ON EMPTY
:A função retornaNULL
; este é o comportamento padrão.DEFAULT
:ovalue
EM VAZIOvalue
fornecido é devolvido. O tipo do valor deve corresponder ao tipo de retorno.ERROR ON EMPTY
:a função gera um erro.
Exemplo:
SELECT JSON_VALUE(
'{
"name" : "Wag",
"type" : "Dog"
}',
'$.score'
DEFAULT 'Nothing found' ON EMPTY
);
Resultado:
Nothing found
Erros
O seguinte pode ser usado para especificar o que acontece quando ocorre um erro:
NULL ON ERROR
:JSON_VALUE()
retornaNULL
; este é o comportamento padrão.DEFAULT
:Este é o valor retornado; seu valor deve corresponder ao do tipo de retorno.value
EM ERROERROR ON ERROR
:um erro é gerado.
Se usado,
ON EMPTY
deve preceder qualquer ON ERROR
cláusula. Especificá-los na ordem errada resulta em um erro de sintaxe. Índices
Conforme mencionado nas notas de lançamento do MySQL 8.0.21, o
JSON_VALUE()
função simplifica a criação de índices em JSON
colunas. Uma chamada para JSON_VALUE(json_doc
, path
RETORNANDO type
)
é equivalente a chamar CAST( JSON_UNQUOTE( JSON_EXTRACT(json_doc
, path
) ) AS type
)
. Aqui está o exemplo usado nas notas de lançamento:
CREATE TABLE inventory(
items JSON,
INDEX i1 ( (JSON_VALUE(items, '$.name' RETURNING CHAR(50))) ),
INDEX i2 ( (JSON_VALUE(items, '$.price' RETURNING DECIMAL(5,2))) ),
INDEX i3 ( (JSON_VALUE(items, '$.quantity' RETURNING UNSIGNED)) )
);