Funkce JSON_QUERY() v Oracle

V databázi Oracle, JSON_QUERY() Funkce vybere a vrátí jednu nebo více hodnot z dat JSON a vrátí tyto hodnoty.

Funkci můžete použít k načtení fragmentů dokumentu JSON.

Syntaxe

Syntaxe vypadá takto:

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

Kde:

• expr je dokument JSON, na který se chcete dotazovat
• JSON_basic_path_expression je cesta SQL/JSON, kterou chcete vrátit z tohoto dokumentu JSON. Funkce používá výraz cesty k vyhodnocení expr a najděte jednu nebo více hodnot JSON, které odpovídají nebo vyhovují výrazu cesty. Výraz cesty musí být textový literál.
• JSON_query_returning_clause určuje datový typ a formát znakového řetězce vráceného funkcí.
• JSON_query_wrapper_clause řídí, zda funkce zabalí vrácené hodnoty do obálky pole (hranaté závorky ([] )).
• JSON_query_on_error_clause určuje hodnotu vrácenou při výskytu určitých chyb.
• JSON_query_on_empty_clause určuje hodnotu vrácenou, pokud není nalezena žádná shoda při vyhodnocování dat JSON pomocí výrazu cesty SQL/JSON.

Podrobné vysvětlení volitelných klauzulí naleznete v dokumentaci Oracle.

Příklad

Zde je příklad demonstrující, jak JSON_QUERY() funkce funguje:

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

Výsledek:

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

Samotné použití znaku dolaru vrátí celý řetězec dat JSON.

S Wrapper

Můžete použít WITH WRAPPER klauzule k zabalení výsledku do obálky pole:

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

Výsledek:

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

Tuto klauzuli musíte zadat, pokud výraz cesty odpovídá jedné skalární hodnotě (hodnota, která není objektem JSON nebo polem JSON) nebo více hodnotám jakéhokoli typu.

Například vrácení následující skalární hodnoty musí být provedeno pomocí WITH WRAPPER klauzule:

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

Výsledek:

[2]

Vynechání WITH WRAPPER klauzule při vrácení skalární hodnoty má za následek vrácenou hodnotu null:

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

Výsledek:

null

Ve výchozím nastavení vrátí SQLcl a SQL*Plus prázdné místo vždy, když null dochází v důsledku SQL SELECT prohlášení.

Můžete však použít SET NULL určit jiný řetězec, který má být vrácen. Zde jsem uvedl, že řetězec null by měl být vrácen.

S podmíněným obalem

Případně můžete použít WITH CONDITIONAL WRAPPER klauzule k zahrnutí obálky pole pouze v případě, že výraz cesty odpovídá jedné skalární hodnotě nebo více hodnotám jakéhokoli typu. Pokud výraz cesty odpovídá jednomu objektu JSON nebo poli JSON, pak je obal pole vynechán:

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;

Výsledek:

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

V tomto případě má pouze skalární hodnotu aplikovaný obal pole.

Aby bylo jasno, tady je to s bezpodmínečným obalem:

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;

Výsledek:

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

Tentokrát mají oba výsledky aplikovaný obal.

Všimněte si, že WITH UNCONDITIONAL WRAPPER je ekvivalentem WITH WRAPPER .

Zpracování chyb

Existuje pět klauzulí, které můžete použít k určení toho, co se má vrátit, kdykoli se vyskytnou určité druhy chyb. Tyto věty jsou:

• NULL ON ERROR – Vrátí hodnotu null, když dojde k chybě. Toto je výchozí.
• ERROR ON ERROR – Vrátí příslušnou chybu Oracle, když dojde k chybě.
• EMPTY ON ERROR – Zadání této klauzule je ekvivalentní zadání EMPTY ARRAY ON ERROR .
• EMPTY ARRAY ON ERROR – Vrátí prázdné pole JSON ([] ), když dojde k chybě.
• EMPTY OBJECT ON ERROR – Vrátí prázdný objekt JSON ({} ), když dojde k chybě.

Zde je příklad:

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;

Výsledek:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}   

Zde je to s ERROR ON ERROR klauzule:

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

Výsledek:

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

Tyto chybové klauzule jsou určeny pro zpracování následujících chyb:

• Prvním argumentem nejsou správně vytvořená data JSON používající přísnou nebo laxní syntaxi JSON
• Při vyhodnocení dat JSON pomocí výrazu cesty SQL/JSON nebyla nalezena žádná shoda. Chování tohoto typu chyby můžete přepsat zadáním JSON_query_on_empty_clause .
• Datový typ návratové hodnoty není dostatečně velký, aby pojal řetězec návratových znaků
• Funkce odpovídá jedné skalární hodnotě nebo více hodnotám libovolného typu a není specifikována klauzule obalu

Zpracování prázdných výsledků

Pokud není nalezena žádná shoda, můžete také použít klauzuli k určení vrácené hodnoty. Tato klauzule vám umožňuje určit jiný výsledek pro tento typ chyby, než jaký je uveden v klauzuli o chybě.

Tyto klauzule jsou:

• NULL ON EMPTY – Pokud není nalezena žádná shoda, vrátí hodnotu null.
• ERROR ON EMPTY – Pokud není nalezena žádná shoda, vrátí příslušnou chybu Oracle.
• EMPTY ON EMPTY – Zadání této klauzule je ekvivalentní zadání EMPTY ARRAY ON EMPTY .
• EMPTY ARRAY ON EMPTY – Vrátí prázdné pole JSON ([] ), když není nalezena žádná shoda.
• EMPTY OBJECT ON EMPTY – Vrátí prázdný objekt JSON ({} ), když není nalezena žádná shoda.

Příklad:

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

Výsledek:

[]

Pokud tuto klauzuli vynecháte, pak klauzule o chybě určuje hodnotu vrácenou, když není nalezena žádná shoda.