JSON_QUERY() Funktion i Oracle

I Oracle Database, JSON_QUERY() funktion väljer och returnerar ett eller flera värden från JSON-data och returnerar dessa värden.

Du kan använda funktionen för att hämta fragment av ett JSON-dokument.

Syntax

Syntaxen ser ut så här:

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

Var:

expr är JSON-dokumentet du vill fråga
JSON_basic_path_expression är SQL/JSON-sökvägen du vill returnera från det JSON-dokumentet. Funktionen använder sökvägsuttrycket för att utvärdera expr och hitta ett eller flera JSON-värden som matchar eller uppfyller sökvägsuttrycket. Sökvägsuttrycket måste vara en bokstavlig text.
JSON_query_returning_clause anger datatypen och formatet för teckensträngen som returneras av funktionen.
JSON_query_wrapper_clause styr om funktionen lindar de returnerade värdena i ett array-omslag (hakparenteser ([] )).
JSON_query_on_error_clause anger värdet som returneras när vissa fel uppstår.
JSON_query_on_empty_clause anger värdet som returneras om ingen matchning hittas när JSON-data utvärderas med SQL/JSON-sökvägsuttrycket.

Se Oracle-dokumentationen för en detaljerad förklaring av de valfria klausulerna.

Exempel

Här är ett exempel för att visa hur JSON_QUERY() funktionen fungerar:

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

Resultat:

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

Att använda dollartecknet i sig returnerar hela strängen med JSON-data.

Med Wrapper

Du kan använda WITH WRAPPER sats för att linda in resultatet i ett array-omslag:

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

Resultat:

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

Du måste ange denna sats om sökvägsuttrycket matchar ett enstaka skalärt värde (ett värde som inte är ett JSON-objekt eller JSON-matris) eller flera värden av någon typ.

Till exempel, returnering av följande skalära värde måste göras med WITH WRAPPER klausul:

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

Resultat:

[2]

Utelämnar WITH WRAPPER sats när man returnerar ett skalärt värde resulterar i att ett nullvärde returneras:

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

Resultat:

null

Som standard returnerar SQLcl och SQL*Plus ett tomt utrymme när null uppstår som ett resultat av en SQL SELECT påstående.

Du kan dock använda SET NULL för att ange en annan sträng som ska returneras. Här specificerade jag att strängen null bör returneras.

Med villkorlig omslag

Alternativt kan du använda WITH CONDITIONAL WRAPPER satsen för att endast inkludera arrayomslaget om sökvägsuttrycket matchar ett enda skalärt värde eller flera värden av valfri typ. Om sökvägsuttrycket matchar ett enstaka JSON-objekt eller JSON-matris utelämnas arrayomslaget:

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;

Resultat:

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

I det här fallet är det bara det skalära värdet som har arrayomslaget tillämpat.

Bara för att vara tydlig, här är den med ett ovillkorligt omslag:

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;

Resultat:

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

Denna gång har båda resultaten applicerat omslaget.

Observera att WITH UNCONDITIONAL WRAPPER är motsvarigheten till WITH WRAPPER .

Felhantering

Det finns fem satser som du kan använda för att specificera vad som ska returneras när vissa typer av fel uppstår. Klausulerna är:

NULL ON ERROR – Returnerar null när ett fel uppstår. Detta är standard.
ERROR ON ERROR – Returnerar lämpligt Oracle-fel när ett fel uppstår.
EMPTY ON ERROR – Att specificera denna sats motsvarar att specificera EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Returnerar en tom JSON-array ([] ) när ett fel uppstår.
EMPTY OBJECT ON ERROR – Returnerar ett tomt JSON-objekt ({} ) när ett fel uppstår.

Här är ett exempel:

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;

Resultat:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Här är den med ERROR ON ERROR klausul:

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

Resultat:

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

Dessa felsatser är till för att hantera följande fel:

Det första argumentet är inte välformad JSON-data med strikt eller slapp JSON-syntax
Ingen matchning hittades när JSON-data utvärderas med SQL/JSON-sökvägsuttrycket. Du kan åsidosätta beteendet för den här typen av fel genom att ange JSON_query_on_empty_clause .
Returvärdets datatyp är inte tillräckligt stor för att innehålla returteckensträngen
Funktionen matchar ett enstaka skalärt värde eller flera värden av valfri typ, och en omslagssats är inte specificerad

Hantera tomma resultat

Du kan också använda en sats för att ange värdet som returneras om ingen matchning hittas. Den här klausulen låter dig ange ett annat utfall för den här typen av fel än det utfall som anges med felklausulerna.

Dessa klausuler är:

NULL ON EMPTY – Returnerar null när ingen matchning hittas.
ERROR ON EMPTY – Returnerar lämpligt Oracle-fel när ingen matchning hittas.
EMPTY ON EMPTY – Att specificera denna sats motsvarar att specificera EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Returnerar en tom JSON-array ([] ) när ingen matchning hittas.
EMPTY OBJECT ON EMPTY – Returnerar ett tomt JSON-objekt ({} ) när ingen matchning hittas.

Exempel:

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

Resultat:

[]

Om du utelämnar den här satsen bestämmer felsatsen värdet som returneras när ingen matchning hittas.