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ć zapytanieJSON_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 ocenyexpr
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śleniuEMPTY
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śleniuEMPTY
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.