JSON_QUERY() Funkcja w Oracle

W bazie danych Oracle JSON_QUERY() funkcja wybiera i zwraca jedną lub więcej wartości z danych JSON i zwraca te wartości.

Możesz użyć tej funkcji, aby pobrać fragmenty dokumentu JSON.

Składnia

Składnia wygląda tak:

JSON_QUERY
  ( expr [ FORMAT JSON ], JSON_basic_path_expression
    [ JSON_query_returning_clause ] [ JSON_query_wrapper_clause ]
    [ JSON_query_on_error_clause ] [ JSON_query_on_empty_clause ]
  )

Gdzie:

expr jest dokumentem JSON, do którego chcesz wysłać zapytanie
JSON_basic_path_expression to ścieżka SQL/JSON, którą chcesz zwrócić z tego dokumentu JSON. Funkcja używa wyrażenia ścieżki do oceny expr i znajdź co najmniej jedną wartość JSON, która pasuje lub spełnia wyrażenie ścieżki. Wyrażenie ścieżki musi być literałem tekstowym.
JSON_query_returning_clause określa typ danych i format ciągu znaków zwracanego przez funkcję.
JSON_query_wrapper_clause kontroluje czy funkcja zawija zwrócone wartości w otoczkę tablicy (nawiasy kwadratowe ([] )).
JSON_query_on_error_clause określa wartość zwracaną w przypadku wystąpienia pewnych błędów.
JSON_query_on_empty_clause określa wartość zwracaną, jeśli nie zostanie znalezione żadne dopasowanie, gdy dane JSON są oceniane za pomocą wyrażenia ścieżki SQL/JSON.

Zobacz dokumentację Oracle, aby uzyskać szczegółowe wyjaśnienie opcjonalnych klauzul.

Przykład

Oto przykład pokazujący, jak JSON_QUERY() funkcja działa:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$')
FROM DUAL;

Wynik:

{"a":1,"b":2,"c":3}

Użycie samego znaku dolara zwraca cały ciąg danych JSON.

Z opakowaniem

Możesz użyć WITH WRAPPER klauzula, aby zawinąć wynik w otoczkę tablicy:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH WRAPPER)
FROM DUAL;

Wynik:

[{"a":1,"b":2,"c":3}]

Musisz określić tę klauzulę, jeśli wyrażenie ścieżki pasuje do pojedynczej wartości skalarnej (wartości, która nie jest obiektem JSON ani tablicy JSON) lub wielu wartości dowolnego typu.

Na przykład, zwrócenie następującej wartości skalarnej musi być wykonane za pomocą WITH WRAPPER klauzula:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH WRAPPER)
FROM DUAL;

Wynik:

[2]

Pominięcie WITH WRAPPER klauzula podczas zwracania wartości skalarnej powoduje zwrócenie wartości null:

SET NULL 'null';
SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$.b')
FROM DUAL;

Wynik:

null

Domyślnie SQLcl i SQL*Plus zwracają spację, gdy null występuje w wyniku polecenia SQL SELECT oświadczenie.

Możesz jednak użyć SET NULL aby określić inny ciąg do zwrócenia. Tutaj określiłem, że ciąg null należy zwrócić.

Z opakowaniem warunkowym

Alternatywnie możesz użyć WITH CONDITIONAL WRAPPER klauzula, aby uwzględnić otokę tablicy tylko wtedy, gdy wyrażenie ścieżki pasuje do pojedynczej wartości skalarnej lub wielu wartości dowolnego typu. Jeśli wyrażenie ścieżki pasuje do pojedynczego obiektu JSON lub tablicy JSON, otoczka tablicy jest pomijana:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH CONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH CONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Wynik:

                    r1     r2 
______________________ ______ 
{"a":1,"b":2,"c":3}    [2]

W tym przypadku tylko wartość skalarna ma zastosowane opakowanie tablicy.

Żeby było jasne, oto jest bezwarunkowe opakowanie:

SELECT 
    JSON_QUERY('{a:1, b:2, c:3}', '$' WITH UNCONDITIONAL WRAPPER) AS "r1",
    JSON_QUERY('{a:1, b:2, c:3}', '$.b' WITH UNCONDITIONAL WRAPPER) AS "r2"
FROM DUAL;

Wynik:

                      r1     r2 
________________________ ______ 
[{"a":1,"b":2,"c":3}]    [2]

Tym razem oba wyniki mają zastosowane opakowanie.

Zwróć uwagę, że WITH UNCONDITIONAL WRAPPER jest odpowiednikiem WITH WRAPPER .

Obsługa błędów

Istnieje pięć klauzul, których możesz użyć, aby określić, co zwrócić, gdy wystąpią pewne rodzaje błędów. Klauzule to:

NULL ON ERROR – Zwraca wartość null, gdy wystąpi błąd. To jest ustawienie domyślne.
ERROR ON ERROR – Zwraca odpowiedni błąd Oracle, gdy wystąpi błąd.
EMPTY ON ERROR – Określenie tej klauzuli jest równoważne określeniu EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Zwraca pustą tablicę JSON ([] ) gdy wystąpi błąd.
EMPTY OBJECT ON ERROR – Zwraca pusty obiekt JSON ({} ) gdy wystąpi błąd.

Oto przykład:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' NULL ON ERROR) AS "r1",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON ERROR) AS "r2",
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY OBJECT ON ERROR) AS "r3"
FROM DUAL;

Wynik:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Tutaj jest z ERROR ON ERROR klauzula:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' ERROR ON ERROR)
FROM DUAL;

Wynik:

Error report -
ORA-40462: JSON_VALUE evaluated to no value

Te klauzule o błędach służą do obsługi następujących błędów:

Pierwszy argument nie jest poprawnie sformułowanymi danymi JSON przy użyciu ścisłej lub luźnej składni JSON
Nie znaleziono dopasowania, gdy dane JSON są oceniane przy użyciu wyrażenia ścieżki SQL/JSON. Możesz zmienić zachowanie tego typu błędu, określając JSON_query_on_empty_clause .
Typ danych zwracanej wartości nie jest wystarczająco duży, aby pomieścić ciąg znaków zwracanych
Funkcja dopasowuje pojedynczą wartość skalarną lub wiele wartości dowolnego typu, a klauzula opakowująca nie jest określona

Obsługa pustych wyników

Możesz również użyć klauzuli, aby określić zwracaną wartość, jeśli nie zostanie znalezione dopasowanie. Ta klauzula pozwala określić inny wynik dla tego typu błędu niż wynik określony w klauzulach błędu.

Te klauzule to:

NULL ON EMPTY – Zwraca wartość null, gdy nie zostanie znalezione żadne dopasowanie.
ERROR ON EMPTY – Zwraca odpowiedni błąd Oracle, gdy nie zostanie znalezione dopasowanie.
EMPTY ON EMPTY – Określenie tej klauzuli jest równoważne określeniu EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Zwraca pustą tablicę JSON ([] ), gdy nie zostanie znalezione żadne dopasowanie.
EMPTY OBJECT ON EMPTY – Zwraca pusty obiekt JSON ({} ), gdy nie zostanie znalezione żadne dopasowanie.

Przykład:

SELECT 
    JSON_QUERY('["a", "b", "c"]', '$[3]' EMPTY ON EMPTY)
FROM DUAL;

Wynik:

[]

Jeśli pominiesz tę klauzulę, klauzula błędu określa wartość zwracaną, gdy nie zostanie znalezione żadne dopasowanie.