JSON_QUERY() Funzione in Oracle

In Oracle Database, il JSON_QUERY() La funzione seleziona e restituisce uno o più valori dai dati JSON e restituisce tali valori.

Puoi utilizzare la funzione per recuperare frammenti di un documento JSON.

Sintassi

La sintassi è questa:

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

Dove:

expr è il documento JSON che vuoi interrogare
JSON_basic_path_expression è il percorso SQL/JSON che vuoi restituire da quel documento JSON. La funzione utilizza l'espressione del percorso per valutare expr e trova uno o più valori JSON che corrispondono o soddisfano l'espressione del percorso. L'espressione del percorso deve essere un valore letterale di testo.
JSON_query_returning_clause specifica il tipo di dati e il formato della stringa di caratteri restituita dalla funzione.
JSON_query_wrapper_clause controlla se la funzione racchiude i valori restituiti in un wrapper di matrice (parentesi quadre ([] )).
JSON_query_on_error_clause specifica il valore restituito quando si verificano determinati errori.
JSON_query_on_empty_clause specifica il valore restituito se non viene trovata alcuna corrispondenza quando i dati JSON vengono valutati utilizzando l'espressione del percorso SQL/JSON.

Consulta la documentazione Oracle per una spiegazione dettagliata delle clausole facoltative.

Esempio

Ecco un esempio per dimostrare come JSON_QUERY() la funzione funziona:

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

Risultato:

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

L'utilizzo del simbolo del dollaro da solo restituisce l'intera stringa di dati JSON.

Con Wrapper

Puoi usare il WITH WRAPPER clausola per racchiudere il risultato in un wrapper di matrice:

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

Risultato:

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

Devi specificare questa clausola se l'espressione del percorso corrisponde a un singolo valore scalare (un valore che non è un oggetto JSON o una matrice JSON) o più valori di qualsiasi tipo.

Ad esempio, la restituzione del seguente valore scalare deve essere eseguita con WITH WRAPPER clausola:

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

Risultato:

[2]

Omettendo il WITH WRAPPER La clausola quando si restituisce un valore scalare comporta la restituzione di un valore nullo:

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

Risultato:

null

Per impostazione predefinita, SQLcl e SQL*Plus restituiscono uno spazio vuoto ogni volta che null si verifica come risultato di un SQL SELECT dichiarazione.

Tuttavia, puoi utilizzare SET NULL per specificare una stringa diversa da restituire. Qui ho specificato che la stringa null deve essere restituito.

Con wrapper condizionale

In alternativa, puoi utilizzare il WITH CONDITIONAL WRAPPER clausola per includere l'array wrapper solo se l'espressione del percorso corrisponde a un singolo valore scalare o a più valori di qualsiasi tipo. Se l'espressione del percorso corrisponde a un singolo oggetto JSON o array JSON, il wrapper dell'array viene omesso:

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;

Risultato:

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

In questo caso, solo il valore scalare ha l'array wrapper applicato.

Tanto per essere chiari, eccolo qui con un wrapper incondizionato:

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;

Risultato:

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

Questa volta entrambi i risultati hanno applicato il wrapper.

Nota che WITH UNCONDITIONAL WRAPPER è l'equivalente di WITH WRAPPER .

Gestione degli errori

Esistono cinque clausole che puoi utilizzare per specificare cosa restituire ogni volta che si verificano determinati tipi di errori. Le clausole sono:

NULL ON ERROR – Restituisce null quando si verifica un errore. Questa è l'impostazione predefinita.
ERROR ON ERROR – Restituisce l'errore Oracle appropriato quando si verifica un errore.
EMPTY ON ERROR – Specificare questa clausola equivale a specificare EMPTY ARRAY ON ERROR .
EMPTY ARRAY ON ERROR – Restituisce un array JSON vuoto ([] ) quando si verifica un errore.
EMPTY OBJECT ON ERROR – Restituisce un oggetto JSON vuoto ({} ) quando si verifica un errore.

Ecco un esempio:

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;

Risultato:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

Eccolo con ERROR ON ERROR clausola:

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

Risultato:

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

Queste clausole di errore servono a gestire i seguenti errori:

Il primo argomento non sono dati JSON ben formati che utilizzano una sintassi JSON rigorosa o lassista
Non viene trovata alcuna corrispondenza quando i dati JSON vengono valutati utilizzando l'espressione del percorso SQL/JSON. Puoi ignorare il comportamento per questo tipo di errore specificando JSON_query_on_empty_clause .
Il tipo di dati del valore restituito non è abbastanza grande da contenere la stringa di caratteri restituita
La funzione corrisponde a un singolo valore scalare oa più valori di qualsiasi tipo e non è specificata una clausola wrapper

Gestione dei risultati vuoti

È inoltre possibile utilizzare una clausola per specificare il valore restituito se non viene trovata alcuna corrispondenza. Questa clausola consente di specificare un esito diverso per questo tipo di errore rispetto all'esito specificato con le clausole di errore.

Queste clausole sono:

NULL ON EMPTY – Restituisce null quando non viene trovata alcuna corrispondenza.
ERROR ON EMPTY – Restituisce l'errore Oracle appropriato quando non viene trovata alcuna corrispondenza.
EMPTY ON EMPTY – Specificare questa clausola equivale a specificare EMPTY ARRAY ON EMPTY .
EMPTY ARRAY ON EMPTY – Restituisce un array JSON vuoto ([] ) quando non viene trovata alcuna corrispondenza.
EMPTY OBJECT ON EMPTY – Restituisce un oggetto JSON vuoto ({} ) quando non viene trovata alcuna corrispondenza.

Esempio:

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

Risultato:

[]

Se ometti questa clausola, la clausola error determina il valore restituito quando non viene trovata alcuna corrispondenza.