JSON_QUERY()-Funktion in Oracle

In der Oracle-Datenbank die JSON_QUERY() Die Funktion wählt einen oder mehrere Werte aus JSON-Daten aus und gibt sie zurück und gibt diese Werte zurück.

Sie können die Funktion verwenden, um Fragmente eines JSON-Dokuments abzurufen.

Syntax

Die Syntax sieht so aus:

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

Wo:

• expr ist das JSON-Dokument, das Sie abfragen möchten
• JSON_basic_path_expression ist der SQL/JSON-Pfad, den Sie von diesem JSON-Dokument zurückgeben möchten. Die Funktion verwendet den Pfadausdruck, um expr auszuwerten und finden Sie einen oder mehrere JSON-Werte, die mit dem Pfadausdruck übereinstimmen oder ihn erfüllen. Der Pfadausdruck muss ein Textliteral sein.
• JSON_query_returning_clause gibt den Datentyp und das Format der von der Funktion zurückgegebenen Zeichenfolge an.
• JSON_query_wrapper_clause steuert, ob die Funktion die zurückgegebenen Werte in einen Array-Wrapper umschließt (eckige Klammern ([] )).
• JSON_query_on_error_clause gibt den Wert an, der zurückgegeben wird, wenn bestimmte Fehler auftreten.
• JSON_query_on_empty_clause gibt den zurückgegebenen Wert an, wenn bei der Auswertung der JSON-Daten mithilfe des SQL/JSON-Pfadausdrucks keine Übereinstimmung gefunden wird.

Eine detaillierte Erläuterung der optionalen Klauseln finden Sie in der Oracle-Dokumentation.

Beispiel

Hier ist ein Beispiel, um zu demonstrieren, wie die JSON_QUERY() Funktion funktioniert:

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

Ergebnis:

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

Die alleinige Verwendung des Dollarzeichens gibt die gesamte Zeichenfolge der JSON-Daten zurück.

Mit Wrapper

Sie können den WITH WRAPPER verwenden -Klausel, um das Ergebnis in einen Array-Wrapper einzuschließen:

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

Ergebnis:

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

Sie müssen diese Klausel angeben, wenn der Pfadausdruck mit einem einzelnen Skalarwert (einem Wert, der kein JSON-Objekt oder JSON-Array ist) oder mehreren Werten eines beliebigen Typs übereinstimmt.

Beispielsweise muss die Rückgabe des folgenden Skalarwerts mit dem WITH WRAPPER erfolgen Klausel:

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

Ergebnis:

[2]

Weglassen des WITH WRAPPER -Klausel führt bei der Rückgabe eines Skalarwerts dazu, dass ein Nullwert zurückgegeben wird:

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

Ergebnis:

null

Standardmäßig geben SQLcl und SQL*Plus ein Leerzeichen zurück, wenn null tritt als Ergebnis eines SQL SELECT auf Erklärung.

Sie können jedoch SET NULL verwenden um eine andere Zeichenfolge anzugeben, die zurückgegeben werden soll. Hier habe ich angegeben, dass der String null zurückgegeben werden soll.

Mit bedingtem Wrapper

Alternativ können Sie den WITH CONDITIONAL WRAPPER verwenden -Klausel, um den Array-Wrapper nur einzuschließen, wenn der Pfadausdruck mit einem einzelnen Skalarwert oder mehreren Werten eines beliebigen Typs übereinstimmt. Wenn der Pfadausdruck mit einem einzelnen JSON-Objekt oder JSON-Array übereinstimmt, wird der Array-Wrapper weggelassen:

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;

Ergebnis:

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

In diesem Fall wird der Array-Wrapper nur auf den Skalarwert angewendet.

Nur um das klarzustellen, hier ist es mit einem bedingungslosen Wrapper:

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;

Ergebnis:

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

Dieses Mal wurde der Wrapper auf beide Ergebnisse angewendet.

Beachten Sie, dass WITH UNCONDITIONAL WRAPPER ist das Äquivalent zu WITH WRAPPER .

Fehlerbehandlung

Es gibt fünf Klauseln, mit denen Sie angeben können, was zurückgegeben werden soll, wenn bestimmte Arten von Fehlern auftreten. Die Klauseln sind:

• NULL ON ERROR – Gibt null zurück, wenn ein Fehler auftritt. Dies ist die Voreinstellung.
• ERROR ON ERROR – Gibt den entsprechenden Oracle-Fehler zurück, wenn ein Fehler auftritt.
• EMPTY ON ERROR – Die Angabe dieser Klausel entspricht der Angabe von EMPTY ARRAY ON ERROR .
• EMPTY ARRAY ON ERROR – Gibt ein leeres JSON-Array zurück ([] ), wenn ein Fehler auftritt.
• EMPTY OBJECT ON ERROR – Gibt ein leeres JSON-Objekt zurück ({} ), wenn ein Fehler auftritt.

Hier ist ein Beispiel:

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;

Ergebnis:

     r1    r2    r3 
_______ _____ _____ 
null    []    {}   

Hier ist es mit dem ERROR ON ERROR Klausel:

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

Ergebnis:

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

Diese Fehlerklauseln dienen zur Behandlung der folgenden Fehler:

• Das erste Argument sind keine wohlgeformten JSON-Daten mit strenger oder laxer JSON-Syntax
• Es wird keine Übereinstimmung gefunden, wenn die JSON-Daten mit dem SQL/JSON-Pfadausdruck ausgewertet werden. Sie können das Verhalten für diesen Fehlertyp überschreiben, indem Sie die JSON_query_on_empty_clause angeben .
• Der Datentyp des Rückgabewerts ist nicht groß genug, um die Rückgabezeichenfolge aufzunehmen
• Die Funktion stimmt mit einem einzelnen Skalarwert oder mehreren Werten eines beliebigen Typs überein, und es wurde keine Wrapper-Klausel angegeben

Umgang mit leeren Ergebnissen

Sie können auch eine Klausel verwenden, um den zurückgegebenen Wert anzugeben, wenn keine Übereinstimmung gefunden wird. Mit dieser Klausel können Sie für diesen Fehlertyp ein anderes Ergebnis angeben als das mit den Fehlerklauseln angegebene Ergebnis.

Diese Klauseln sind:

• NULL ON EMPTY – Gibt null zurück, wenn keine Übereinstimmung gefunden wird.
• ERROR ON EMPTY – Gibt den entsprechenden Oracle-Fehler zurück, wenn keine Übereinstimmung gefunden wird.
• EMPTY ON EMPTY – Die Angabe dieser Klausel entspricht der Angabe von EMPTY ARRAY ON EMPTY .
• EMPTY ARRAY ON EMPTY – Gibt ein leeres JSON-Array zurück ([] ), wenn keine Übereinstimmung gefunden wird.
• EMPTY OBJECT ON EMPTY – Gibt ein leeres JSON-Objekt zurück ({} ), wenn keine Übereinstimmung gefunden wird.

Beispiel:

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

Ergebnis:

[]

Wenn Sie diese Klausel weglassen, bestimmt die Fehlerklausel den zurückgegebenen Wert, wenn keine Übereinstimmung gefunden wird.