OracleのJSON_QUERY（）関数

Oracle Databaseでは、JSON_QUERY() 関数は、JSONデータから1つ以上の値を選択して返し、それらの値を返します。

この関数を使用して、JSONドキュメントのフラグメントを取得できます。

構文

構文は次のようになります：

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

場所：

expr クエリするJSONドキュメントです
JSON_basic_path_expression そのJSONドキュメントから返すSQL/JSONパスです。この関数はパス式を使用してexprを評価します パス式に一致する、または満たす1つ以上のJSON値を見つけます。パス式はテキストリテラルである必要があります。
JSON_query_returning_clause 関数によって返される文字列のデータ型と形式を指定します。
JSON_query_wrapper_clause 関数が戻り値を配列ラッパー（角かっこ（[]）でラップするかどうかを制御します））。
JSON_query_on_error_clause 特定のエラーが発生したときに返される値を指定します。
JSON_query_on_empty_clause SQL/JSONパス式を使用してJSONデータを評価するときに一致するものが見つからない場合に返される値を指定します。

オプションの句の詳細な説明については、Oracleのドキュメントを参照してください。

例

JSON_QUERY()がどのように行われるかを示す例を次に示します。機能は動作します：

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

結果：

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

ドル記号を単独で使用すると、JSONデータの文字列全体が返されます。

ラッパー付き

WITH WRAPPERを使用できます結果を配列ラッパーでラップする句：

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

結果：

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

パス式が単一のスカラー値（JSONオブジェクトまたはJSON配列ではない値）または任意のタイプの複数の値と一致する場合は、この句を指定する必要があります。

たとえば、次のスカラー値を返すには、WITH WRAPPERを使用する必要があります。条項：

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

結果：

[2]

WITH WRAPPERを省略しますスカラー値を返すときの句により、null値が返されます：

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

結果：

null

デフォルトでは、SQLclおよびSQL * Plusは、nullの場合は常に空白を返します。 SQL SELECTの結果として発生します声明。

ただし、SET NULLは使用できます返される別の文字列を指定します。ここでは、文字列nullを指定しました返却する必要があります。

条件付きラッパー付き

または、WITH CONDITIONAL WRAPPERを使用することもできますパス式が単一のスカラー値または任意のタイプの複数の値に一致する場合にのみ配列ラッパーを含める句。パス式が単一のJSONオブジェクトまたはJSON配列と一致する場合、配列ラッパーは省略されます：

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;

結果：

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

この場合、スカラー値のみに配列ラッパーが適用されます。

明確にするために、ここでは無条件のラッパーを使用しています：

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;

結果：

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

今回は両方の結果にラッパーが適用されています。

WITH UNCONDITIONAL WRAPPERに注意してください WITH WRAPPERと同等です。

エラー処理

特定の種類のエラーが発生したときに何を返すかを指定するために使用できる5つの句があります。条項は次のとおりです。

NULL ON ERROR –エラーが発生した場合はnullを返します。これがデフォルトです。
ERROR ON ERROR –エラーが発生すると、適切なOracleエラーを返します。
EMPTY ON ERROR –この句を指定することは、EMPTYを指定することと同じです。 ARRAY ON ERROR 。
EMPTY ARRAY ON ERROR –空のJSON配列を返します（[] ）エラーが発生したとき。
EMPTY OBJECT ON ERROR –空のJSONオブジェクトを返します（{} ）エラーが発生したとき。

次に例を示します：

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;

結果：

     r1    r2    r3 
_______ _____ _____ 
null    []    {}

これがERROR ON ERRORです。条項：

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

結果：

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

これらのエラー句は、次のエラーを処理するためのものです。

最初の引数は、厳密または緩いJSON構文を使用した整形式のJSONデータではありません
SQL / JSONパス式を使用してJSONデータを評価すると、一致するものが見つかりません。 JSON_query_on_empty_clauseを指定することで、このタイプのエラーの動作をオーバーライドできます。 。
戻り値のデータ型は、戻り文字列を保持するのに十分な大きさではありません
関数は単一のスカラー値または任意のタイプの複数の値に一致し、ラッパー句は指定されていません

空の結果の処理

句を使用して、一致するものが見つからない場合に返される値を指定することもできます。この句を使用すると、このタイプのエラーに対して、エラー句で指定された結果とは異なる結果を指定できます。

これらの条項は次のとおりです。

NULL ON EMPTY –一致するものが見つからない場合はnullを返します。
ERROR ON EMPTY –一致するものが見つからない場合、適切なOracleエラーを返します。
EMPTY ON EMPTY –この句を指定することは、EMPTYを指定することと同じです。 ARRAY ON EMPTY 。
EMPTY ARRAY ON EMPTY –空のJSON配列を返します（[] ）一致するものが見つからない場合。
EMPTY OBJECT ON EMPTY –空のJSONオブジェクトを返します（{} ）一致するものが見つからない場合。

例：

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

結果：

[]

この句を省略すると、エラー句によって、一致するものが見つからない場合に返される値が決まります。