MariaDB JSON_SEARCH() Explicado

No MariaDB, JSON_SEARCH() é uma função interna que permite obter o caminho para um determinado valor em um documento JSON.

Ele aceita o documento JSON e uma string como argumentos e retorna o caminho para a string fornecida no documento.

Sintaxe

A sintaxe fica assim:

JSON_SEARCH(
    json_doc, 
    return_arg, 
    search_str[, escape_char[, path] ...]
    )

Onde:

json_doc é o documento JSON e search_str é a string.
return_arg é a palavra-chave one ou all . Se você usar one , apenas o primeiro caminho é retornado. Quaisquer outras ocorrências são ignoradas. Qual caminho é considerado “primeiro” é indefinido (de acordo com a documentação do MariaDB). Se all for especificado, os caminhos de todas as ocorrências serão retornados. Se houver vários caminhos, eles serão encapsulados automaticamente como uma matriz.
O escape_char argumento é um caractere opcional para ser usado como caractere de escape.
O path argument é um argumento opcional para determinar onde o caminho de "nível superior" começa no documento JSON.

Exemplo

Segue um exemplo para demonstrar:

SET @json = '
    { 
        "name" : "Wag", 
        "type" : "Dog" 
    }';

SELECT JSON_SEARCH(@json, 'one', 'Wag');

Resultado:

+----------------------------------+| JSON_SEARCH(@json, 'um', 'Wag') |+------------------------------------------------+ | "$.nome" |+----------------------------------+

Aqui está um exemplo de retorno do caminho para um elemento em uma matriz:

SET @json = '
    { 
        "product" : "Left Handed Screwdriver", 
        "sizes" : [ "Small", "Medium", "Large" ],
    }';

SELECT JSON_SEARCH(@json, 'one', 'Medium');

Resultado:

+-------------------------------------+| JSON_SEARCH(@json, 'um', "Médio") |+------------------------------------------------- --+| "$.sizes[1]" |+------------------------------------------------+ 
 As matrizes são baseadas em zero e, portanto, $.sizes[1] refere-se ao segundo elemento na matriz. 
 Várias ocorrências
 
 Se você deseja retornar todos os caminhos que contêm a string, use all em vez de one para o segundo argumento. 
 SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'all', 'Dog'); 
 
 Resultado:
 +----------------------------------+| JSON_SEARCH(@json, 'todos', "Cão") |+------------------------------------------------+ | ["$[0].type", "$[1].type"] |+----------------------------- -----+
 
 Se alterarmos all para one , eis o que acontece:
 SET @json = '[
    { "name": "Wag", "type": "Dog", "weight": 20 },
    { "name": "Bark", "type": "Dog", "weight": 10 },
    { "name": "Meow", "type": "Cat", "weight": 7 }
]';

SELECT JSON_SEARCH(@json, 'one', 'Dog'); 
 
 Resultado:
 +----------------------------------+| JSON_SEARCH(@json, 'um', "Cão") |+------------------------------------------------+ | "$[0].type" |+----------------------------------+
 
 Apenas um caminho é retornado. 
 Especifique um caminho
 
 Aqui está um exemplo que especifica um caminho para pesquisar no documento:
 SET @json = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "NZ Dog Award" : "Top Dog", 
                "New York Marathon" : "Fastest Animal", 
                "Sumo 2021" : "Biggest Dog"
            }
        }
    }
';
SELECT JSON_SEARCH(
    @json, 
    'all',
    '%dog%',
    NULL,
    '$.details.awards'
    ) AS Result; 
 
 Resultado:
 +---------------------------------------------- -------------------+| Resultado |+---------------------------------------------------------- ------------------+| ["$.details.awards.NZ Dog Award", "$.details.awards.Sumo 2021"] |+------------------------ ------------------------------+
 
 Neste caso, a string dog na verdade, ocorre três vezes no documento, mas apenas duas vezes abaixo do caminho especificado. 
 
 Além disso, usamos NULL para o argumento do caractere de escape, que resulta no uso do caractere de escape padrão, que é a barra invertida (\ ). 
 Caractere de escape padrão
 
 Por padrão, o caractere de escape é uma barra invertida (\ ). 
 
 Exemplo:
 SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my\%pwd') AS "Escaped"; 
 
 Resultado:
 +---------------------------------------+------- -----+| Não escapou | Escapou |+--------------------------------------+-------- ----+| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |+-------------------------------------------------+- -----------+
 
 O sinal de porcentagem (% ) é um caractere curinga que corresponde a qualquer número de caracteres. Portanto, se não escaparmos, ele corresponderá a qualquer número de caracteres, incluindo caracteres que não são sinais de porcentagem. 
 
 Mas quando escapamos o sinal de porcentagem com o caractere de escape, ele só corresponderá quando houver exatamente um sinal de porcentagem nesse local. 
 
 Os resultados acima refletem isso. 
 Especifique um caractere de escape personalizado
 
 Você pode especificar um caractere de escape personalizado, se necessário. Para fazer isso, forneça-o como o quarto argumento. 
 
 Exemplo:
 SET @json = '[
    { "uid": "Wag", "pwd": "my%pwd" },
    { "uid": "Bark", "pwd": "my%%%pwd" },
    { "uid": "Bark", "pwd": "myBIGpwd" }
]';

SELECT 
    JSON_SEARCH(@json, 'all', 'my%pwd', '!') AS "Not Escaped",
    JSON_SEARCH(@json, 'all', 'my!%pwd', '!') AS "Escaped"; 
 
 Resultado:
 +---------------------------------------+------- -----+| Não escapou | Escapou |+--------------------------------------+-------- ----+| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |+-------------------------------------------------+- -----------+
 
 Assim, obtemos o mesmo resultado do exemplo anterior. A única diferença é que especificamos um caractere de escape diferente. Nesse caso, especificamos que o ponto de exclamação (! ) é o caractere de escape. 
 Argumentos nulos
 
 Se algum dos argumentos de string de pesquisa, string de pesquisa ou caminho for NULL , o resultado é NULL :
 SELECT 
    JSON_SEARCH(null, 'all', 's', '', '$') AS a,
    JSON_SEARCH('{"a":1}', 'all', null, '', '$') AS b,
    JSON_SEARCH('{"a":1}', 'all', 's', '', null) AS c; 
 
 Resultado:
 +------+------+------+| um | b | c |+------+------+------+| NULO | NULO | NULL |+------+------+------+
 Contagem de parâmetros incorreta
 
 Não fornecer argumentos resulta em um erro:
 SELECT JSON_SEARCH(); 
 
 Resultado:
 ERRO 1582 (42000):contagem de parâmetro incorreta na chamada para a função nativa 'JSON_SEARCH'
 
 É o mesmo quando você fornece poucos argumentos:
 SELECT JSON_SEARCH('{"a":1}', 'all'); 
 
 Resultado:
 ERRO 1582 (42000):contagem de parâmetro incorreta na chamada para a função nativa 'JSON_SEARCH'