JSON_QUERY() Functie in Oracle

In Oracle Database, de JSON_QUERY() functie selecteert en retourneert een of meer waarden uit JSON-gegevens en retourneert die waarden.

U kunt de functie gebruiken om fragmenten van een JSON-document op te halen.

Syntaxis

De syntaxis gaat als volgt:

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 ]
  )

Waar:

expr is het JSON-document dat u wilt opvragen
JSON_basic_path_expression is het SQL/JSON-pad dat u uit dat JSON-document wilt retourneren. De functie gebruikt de path-expressie om expr . te evalueren en zoek een of meer JSON-waarden die overeenkomen met of voldoen aan de padexpressie. De paduitdrukking moet letterlijk een tekst zijn.
JSON_query_returning_clause specificeert het gegevenstype en de indeling van de tekenreeks die door de functie wordt geretourneerd.
JSON_query_wrapper_clause bepaalt of de functie de geretourneerde waarden in een array-wrapper plaatst (vierkante haken ([] )).
JSON_query_on_error_clause specificeert de waarde die wordt geretourneerd wanneer bepaalde fouten optreden.
JSON_query_on_empty_clause specificeert de waarde die wordt geretourneerd als er geen overeenkomst wordt gevonden wanneer de JSON-gegevens worden geëvalueerd met behulp van de SQL/JSON-padexpressie.

Zie de Oracle-documentatie voor een gedetailleerde uitleg van de optionele clausules.

Voorbeeld

Hier is een voorbeeld om te demonstreren hoe de JSON_QUERY() functie werkt:

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

Resultaat:

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

Als u alleen het dollarteken gebruikt, wordt de hele reeks JSON-gegevens geretourneerd.

Met wikkel

U kunt de WITH WRAPPER . gebruiken clausule om het resultaat in een array-wrapper te verpakken:

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

Resultaat:

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

U moet deze clausule opgeven als de padexpressie overeenkomt met een enkele scalaire waarde (een waarde die geen JSON-object of JSON-array is) of meerdere waarden van welk type dan ook.

Het retourneren van de volgende scalaire waarde moet bijvoorbeeld worden gedaan met de WITH WRAPPER clausule:

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

Resultaat:

[2]

Het weglaten van de WITH WRAPPER clausule bij het retourneren van een scalaire waarde resulteert in een null-waarde die wordt geretourneerd:

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

Resultaat:

null

Standaard retourneren SQLcl en SQL*Plus een spatie wanneer null treedt op als resultaat van een SQL SELECT uitspraak.

U kunt echter SET NULL . gebruiken om een andere tekenreeks op te geven die moet worden geretourneerd. Hier heb ik gespecificeerd dat de string null moet worden geretourneerd.

Met voorwaardelijke wrapper

Als alternatief kunt u de WITH CONDITIONAL WRAPPER . gebruiken om de array-wrapper alleen op te nemen als de padexpressie overeenkomt met een enkele scalaire waarde of meerdere waarden van een willekeurig type. Als de padexpressie overeenkomt met een enkel JSON-object of JSON-array, wordt de array-wrapper weggelaten:

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;

Resultaat:

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

In dit geval wordt alleen op de scalaire waarde de array-wrapper toegepast.

Voor de duidelijkheid, hier is het met een onvoorwaardelijke verpakking:

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;

Resultaat:

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

Deze keer hebben beide resultaten de wrapper aangebracht.

Merk op dat WITH UNCONDITIONAL WRAPPER is het equivalent van WITH WRAPPER .

Foutafhandeling

Er zijn vijf clausules die u kunt gebruiken om te specificeren wat moet worden geretourneerd wanneer bepaalde soorten fouten optreden. De clausules zijn:

NULL ON ERROR – Retourneert null wanneer er een fout optreedt. Dit is de standaardinstelling.
ERROR ON ERROR – Retourneert de juiste Oracle-fout wanneer een fout optreedt.
EMPTY ON ERROR – Het specificeren van deze clausule is gelijk aan het specificeren van EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Retourneert een lege JSON-array ([] ) wanneer er een fout optreedt.
EMPTY OBJECT ON ERROR – Retourneert een leeg JSON-object ({} ) wanneer er een fout optreedt.

Hier is een voorbeeld:

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;

Resultaat:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Hier is het met de ERROR ON ERROR clausule:

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

Resultaat:

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

Deze foutclausules zijn voor het afhandelen van de volgende fouten:

Het eerste argument is geen goed gevormde JSON-gegevens die een strikte of lakse JSON-syntaxis gebruiken
Er wordt geen overeenkomst gevonden wanneer de JSON-gegevens worden geëvalueerd met behulp van de SQL/JSON-padexpressie. U kunt het gedrag voor dit type fout overschrijven door de JSON_query_on_empty_clause op te geven .
Het gegevenstype van de retourwaarde is niet groot genoeg om de tekenreeks van het retourteken te bevatten
De functie komt overeen met een enkele scalaire waarde of meerdere waarden van elk type, en er is geen wrapper-clausule opgegeven

Lege resultaten afhandelen

U kunt ook een clausule gebruiken om de waarde op te geven die wordt geretourneerd als er geen overeenkomst wordt gevonden. Met deze clausule kunt u een andere uitkomst voor dit type fout specificeren dan de uitkomst die is gespecificeerd met de foutclausules.

Deze clausules zijn:

NULL ON EMPTY – Retourneert null wanneer er geen overeenkomst is gevonden.
ERROR ON EMPTY – Retourneert de juiste Oracle-fout wanneer er geen overeenkomst wordt gevonden.
EMPTY ON EMPTY – Het specificeren van deze clausule is gelijk aan het specificeren van EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Retourneert een lege JSON-array ([] ) wanneer er geen overeenkomst is gevonden.
EMPTY OBJECT ON EMPTY – Retourneert een leeg JSON-object ({} ) wanneer er geen overeenkomst is gevonden.

Voorbeeld:

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

Resultaat:

[]

Als u deze clausule weglaat, bepaalt de foutclausule de waarde die wordt geretourneerd wanneer er geen overeenkomst wordt gevonden.