JSON_QUERY() Funktion i Oracle

I Oracle Database er JSON_QUERY() funktion vælger og returnerer en eller flere værdier fra JSON-data og returnerer disse værdier.

Du kan bruge funktionen til at hente fragmenter af et JSON-dokument.

Syntaks

Syntaksen ser sådan ud:

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

Hvor:

expr er det JSON-dokument, du vil forespørge på
JSON_basic_path_expression er den SQL/JSON-sti, du vil returnere fra det JSON-dokument. Funktionen bruger stiudtrykket til at evaluere expr og find en eller flere JSON-værdier, der matcher eller opfylder stiudtrykket. Stiudtrykket skal være en bogstavelig tekst.
JSON_query_returning_clause angiver datatypen og formatet for tegnstrengen, der returneres af funktionen.
JSON_query_wrapper_clause kontrollerer, om funktionen ombryder de returnerede værdier i en array-indpakning (firkantede parenteser ([] )).
JSON_query_on_error_clause angiver den værdi, der returneres, når visse fejl opstår.
JSON_query_on_empty_clause angiver den returnerede værdi, hvis der ikke findes noget match, når JSON-dataene evalueres ved hjælp af SQL/JSON-stiudtrykket.

Se Oracle-dokumentationen for en detaljeret forklaring af de valgfrie klausuler.

Eksempel

Her er et eksempel for at demonstrere, hvordan JSON_QUERY() funktion virker:

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

Resultat:

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

Brug af dollartegnet i sig selv returnerer hele strengen af JSON-data.

Med Wrapper

Du kan bruge WITH WRAPPER klausul for at pakke resultatet ind i en array wrapper:

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

Resultat:

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

Du skal angive denne klausul, hvis stiudtrykket matcher en enkelt skalarværdi (en værdi, der ikke er et JSON-objekt eller et JSON-array) eller flere værdier af enhver type.

For eksempel skal returnering af følgende skalarværdi ske med WITH WRAPPER klausul:

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

Resultat:

[2]

Udeladelse af WITH WRAPPER klausul, når en skalarværdi returneres, resulterer i, at en nulværdi returneres:

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

Resultat:

null

Som standard returnerer SQLcl og SQL*Plus et tomt mellemrum, når null opstår som et resultat af en SQL SELECT udmelding.

Du kan dog bruge SET NULL for at angive en anden streng, der skal returneres. Her specificerede jeg, at strengen null skal returneres.

Med betinget indpakning

Alternativt kan du bruge WITH CONDITIONAL WRAPPER klausul for kun at inkludere array-indpakningen, hvis stiudtrykket matcher en enkelt skalarværdi eller flere værdier af enhver type. Hvis stiudtrykket matcher et enkelt JSON-objekt eller JSON-array, udelades array-indpakningen:

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 dette tilfælde er det kun den skalære værdi, der har array-omslaget anvendt.

Bare for at være klar, her er det med en ubetinget indpakning:

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]

Denne gang har begge resultater indpakningen påsat.

Bemærk, at WITH UNCONDITIONAL WRAPPER svarer til WITH WRAPPER .

Fejlhåndtering

Der er fem klausuler, som du kan bruge til at angive, hvad der skal returneres, når der opstår visse typer fejl. Klausulerne er:

NULL ON ERROR – Returnerer null, når der opstår en fejl. Dette er standarden.
ERROR ON ERROR – Returnerer den relevante Oracle-fejl, når der opstår en fejl.
EMPTY ON ERROR – Angivelse af denne klausul svarer til at angive EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Returnerer et tomt JSON-array ([] ), når der opstår en fejl.
EMPTY OBJECT ON ERROR – Returnerer et tomt JSON-objekt ({} ), når der opstår en fejl.

Her er et eksempel:

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    []    {}

Her er 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

Disse fejlsætninger er til håndtering af følgende fejl:

Det første argument er ikke velformede JSON-data, der bruger streng eller slap JSON-syntaks
Der blev ikke fundet noget match, når JSON-dataene evalueres ved hjælp af SQL/JSON-stiudtrykket. Du kan tilsidesætte adfærden for denne type fejl ved at angive JSON_query_on_empty_clause .
Returværdidatatypen er ikke stor nok til at indeholde returtegnstrengen
Funktionen matcher en enkelt skalarværdi eller flere værdier af en hvilken som helst type, og der er ikke angivet en wrapper-sætning

Håndtering af tomme resultater

Du kan også bruge en klausul til at angive den returnerede værdi, hvis der ikke findes noget match. Denne klausul giver dig mulighed for at angive et andet udfald for denne type fejl end det resultat, der er angivet med fejlklausulerne.

Disse klausuler er:

NULL ON EMPTY – Returnerer null, når der ikke findes noget match.
ERROR ON EMPTY – Returnerer den relevante Oracle-fejl, når der ikke findes noget match.
EMPTY ON EMPTY – Angivelse af denne klausul svarer til at angive EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Returnerer et tomt JSON-array ([] ), når der ikke findes noget match.
EMPTY OBJECT ON EMPTY – Returnerer et tomt JSON-objekt ({} ), når der ikke findes noget match.

Eksempel:

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

Resultat:

[]

Hvis du udelader denne klausul, bestemmer fejlsætningen den værdi, der returneres, når der ikke findes noget match.