MariaDB JSON_SEARCH() Objaśnienie

W MariaDB, JSON_SEARCH() to wbudowana funkcja, która pozwala uzyskać ścieżkę do danej wartości w dokumencie JSON.

Akceptuje dokument JSON i ciąg znaków jako argumenty i zwraca ścieżkę do podanego ciągu w dokumencie.

Składnia

Składnia wygląda tak:

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

Gdzie:

json_doc to dokument JSON i search_str jest ciągiem.
return_arg to słowo kluczowe one lub all . Jeśli używasz one , zwracana jest tylko pierwsza ścieżka. Wszelkie inne zdarzenia są ignorowane. Która ścieżka jest uważana za „pierwszą” jest niezdefiniowana (zgodnie z dokumentacją MariaDB). Jeśli all jest określony, zwracane są ścieżki wszystkich wystąpień. Jeśli istnieje wiele ścieżek, są one automatycznie zawijane jako tablica.
escape_char argument jest opcjonalnym znakiem używanym jako znak ucieczki.
path argument jest opcjonalnym argumentem określającym, gdzie zaczyna się ścieżka „najwyższego poziomu” w dokumencie JSON.

Przykład

Oto przykład do zademonstrowania:

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

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

Wynik:

+----------------------------------+
| JSON_SEARCH(@json, 'one', 'Wag') |
+----------------------------------+
| "$.name"                         |
+----------------------------------+

Oto przykład zwracania ścieżki do elementu w tablicy:

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

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

Wynik:

+-------------------------------------+
| JSON_SEARCH(@json, 'one', "Medium") |
+-------------------------------------+
| "$.sizes[1]"                        |
+-------------------------------------+

Tablice są liczone od zera, więc $.sizes[1] odnosi się do drugiego elementu w tablicy.

Wiele wystąpień

Jeśli chcesz zwrócić wszystkie ścieżki zawierające ciąg, użyj all zamiast one dla drugiego argumentu.

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');

Wynik:

+----------------------------------+
| JSON_SEARCH(@json, 'all', "Dog") |
+----------------------------------+
| ["$[0].type", "$[1].type"]       |
+----------------------------------+

Jeśli zmienimy all do one , dzieje się tak:

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');

Wynik:

+----------------------------------+
| JSON_SEARCH(@json, 'one', "Dog") |
+----------------------------------+
| "$[0].type"                      |
+----------------------------------+

Zwracana jest tylko jedna ścieżka.

Określ ścieżkę

Oto przykład określający ścieżkę wyszukiwania w dokumencie:

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;

Wynik:

+-----------------------------------------------------------------+
| Result                                                          |
+-----------------------------------------------------------------+
| ["$.details.awards.NZ Dog Award", "$.details.awards.Sumo 2021"] |
+-----------------------------------------------------------------+

W tym przypadku ciąg dog faktycznie występuje trzy razy w dokumencie, ale tylko dwa razy poniżej określonej ścieżki.

Ponadto użyliśmy NULL dla argumentu znaku ucieczki, co powoduje użycie domyślnego znaku ucieczki, którym jest odwrotny ukośnik (\ ).

Domyślna postać ucieczki

Domyślnie znakiem zmiany znaczenia jest ukośnik odwrotny (\ ).

Przykład:

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";

Wynik:

+--------------------------------------+------------+
| Not Escaped                          | Escaped    |
+--------------------------------------+------------+
| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |
+--------------------------------------+------------+

Znak procentowy (% ) to znak wieloznaczny, który odpowiada dowolnej liczbie znaków. Dlatego, jeśli go nie zmienimy, dopasuje dowolną liczbę znaków, w tym znaki, które nie są znakami procentowymi.

Ale kiedy zmienimy znak procentowy ze znakiem ucieczki, będzie on pasował tylko wtedy, gdy w tej lokalizacji znajduje się dokładnie jeden znak procentowy.

Powyższe wyniki odzwierciedlają to.

Określ niestandardową postać ucieczki

W razie potrzeby możesz określić niestandardowy znak ucieczki. Aby to zrobić, podaj go jako czwarty argument.

Przykład:

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";

Wynik:

+--------------------------------------+------------+
| Not Escaped                          | Escaped    |
+--------------------------------------+------------+
| ["$[0].pwd", "$[1].pwd", "$[2].pwd"] | "$[0].pwd" |
+--------------------------------------+------------+

Otrzymujemy więc ten sam wynik, co w poprzednim przykładzie. Jedyna różnica polega na tym, że określiliśmy inny znak ucieczki. W tym przypadku określiliśmy, że znak wykrzyknika (! ) to znak ucieczki.

Argumenty zerowe

Jeśli którykolwiek z ciągów wyszukiwania, ciągu wyszukiwania lub argumentów ścieżki ma wartość NULL , wynik to 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;

Wynik:

+------+------+------+
| a    | b    | c    |
+------+------+------+
| NULL | NULL | NULL |
+------+------+------+

Nieprawidłowa liczba parametrów

Brak argumentów skutkuje błędem:

SELECT JSON_SEARCH();

Wynik:

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_SEARCH'

Tak samo jest, gdy podasz za mało argumentów:

SELECT JSON_SEARCH('{"a":1}', 'all');

Wynik:

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_SEARCH'