282 JSONのデータ構造
PL/SQLでJSONデータを処理するには、次のデータ構造を使用できます。
ノート:
get_Date
ファンクションのDATE
値の時間コンポーネントは切り捨てられます。時間コンポーネントを保存する場合は、get_Timestamp
を使用してから、CAST AS DATE
を使用して時間コンポーネントを持つSQL日付に変換します。
282.1 JSON_ELEMENT_Tオブジェクト・タイプ
JSON_ELEMENT_T
は、JSON_OBJECT_T
、JSON_SCALAR_T
およびJSON_ARRAY_T
オブジェクト・タイプのスーパータイプです。
説明
次の点に注意してください。
-
JSON_ELEMENT_Tのインスタンスを作成するには、
parse
またはload
ファンクションを使用します。詳細は、次の項「コンストラクタ」を参照してください。 -
空のJSON_ELEMENT_Tインスタンスを作成することはできません。空のJSONコンテナを作成するには、いずれかのサブタイプに基づいてJSONコンテナを作成します。
-
JSON_ELEMENT_Tをサブタイプ(JSON_OBJECT_Tなど)に変換するには、TREAT ASを使用して明示的な変換を実行する必要があります。次に例を示します。
TREAT (elem AS JSON_OBJECT_T)
コンストラクタ
JSON_ELEMENT_Tインスタンスは、parse
またはload
ファンクションを使用して作成します。parse
ファンクションは入力としてVARCHAR2、CLOBまたはBLOBデータを取り、JSON_ELEMENT_Tインスタンスを戻します。同様に、load
ファンクションは、入力としてJSONタイプを取ります。
STATIC FUNCTION parse(jsn VARCHAR2) RETURN JSON_ELEMENT_T STATIC FUNCTION parse(jsn CLOB) RETURN JSON_ELEMENT_T STATIC FUNCTION parse(jsn BLOB) RETURN JSON_ELEMENT_T STATIC FUNCTION parse(jsn BLOB, FORMAT IN VARCHAR2) RETURN JSON_ELEMENT_T STATIC FUNCTION load(jsn JSON) RETURN JSON_Element_T,
UTF8でエンコードされたJSONのみがBLOBとして渡されます。
parse
ファンクションは、入力としてJSON文字列を取り、JSONデータの内部表現を設定します。提供された入力が有効なJSONでない場合、エラー・メッセージが生成されます。有効なJSONは、"IS JSON" SQL条件のLAXチェックに合格する必要があります。load
ファンクションの入力はJSONタイプであるため、JSON構文チェックは必要ありません。
シリアライズおよび変換
JSON_ELEMENT_T
インスタンス(およびすべてのサブタイプ)は、JSON文字列へのシリアライズ、JSONタイプへの変換、日付や数値などのSQL値への変換(スカラー値の場合)が可能です。シリアライズはparseファンクションの逆であり、JSONデータのインメモリー表現の文字列表現が生成され、適切なSQLタイプとして戻されます。
シリアライズおよび変換のファンクションは、次のとおりです。
MEMBER FUNCTION to_String RETURN VARCHAR2 MEMBER FUNCTION stringify RETURN VARCHAR2 MEMBER FUNCTION to_Clob RETURN CLOB MEMBER FUNCTION to_Blob RETURN BLOB MEMBER PROCEDURE to_Clob(c IN OUT CLOB) MEMBER PROCEDURE to_Blob(c IN OUT BLOB) MEMBER FUNCTION to_Json RETURN JSON MEMBER FUNCTION to_Number RETURN NUMBER MEMBER FUNCTION to_Date RETURN DATE MEMBER FUNCTION to_Timestamp RETURN TIMESTAMP MEMBER FUNCTION to_Boolean RETURN BOOLEAN
FUNCTION文字列化は、to_Stringのシノニムです。どちらも機能は同じです。
to_Clob
およびto_Blob
プロシージャは、CLOBまたはBLOB入力を受け入れます。これによって、シリアライズの宛先として使用されるLOBを提供できます。たとえば、EMPTY_LOB
を提供できます。入力のLOBはNULL
にできません。
to_Clob
ファンクションを使用すると、新しいCLOBが作成されます。最初にCLOBを作成しない場合は、to_Clob
またはto_Blob
ファンクションを使用できます。これらのファンクションはパラメータを取らずに、一時的なLOBを生成します。
to_Blob
は、UTF8形式へのシリアライズのみを行います。
イントロスペクション
イントロスぺクションを行うと、JSONオブジェクトを変更することなくJSONオブジェクトのプロパティを検出できます。イントロスペクションのファンクションは次のとおりです。
MEMBER FUNCTION has(key VARCHAR2) RETURN BOOLEAN, MEMBER FUNCTION is_Object RETURN BOOLEAN MEMBER FUNCTION is_Array RETURN BOOLEAN MEMBER FUNCTION is_Scalar RETURN BOOLEAN MEMBER FUNCTION is_String RETURN BOOLEAN MEMBER FUNCTION is_Number RETURN BOOLEAN MEMBER FUNCTION is_Boolean RETURN BOOLEAN MEMBER FUNCTION is_True RETURN BOOLEAN MEMBER FUNCTION is_False RETURN BOOLEAN MEMBER FUNCTION is_Null RETURN BOOLEAN MEMBER FUNCTION is_Date RETURN BOOLEAN MEMBER FUNCTION is_Timestamp RETURN BOOLEAN MEMBER FUNCTION get_Size RETURN NUMBER
has
ファンクションは、指定された名前がJSON_OBJECT_Tオブジェクトに存在するかどうかをチェックします。
get_size
ファンクションの戻り値は、JSONタイプによって異なります。
-
スカラーの場合、
1
が戻されます。 -
オブジェクトの場合、キーの数が戻されます。
-
配列の場合、アイテムの数が戻されます。
テキストJSONでは、日付とタイムスタンプがネイティブにサポートされません。通常、これらは文字列としてモデル化されます。JSONタイプを使用すると、日付とタイムスタンプをネイティブに保持できます。Document Object Model (DOM)インタフェースでは、日付とタイムスタンプをスカラー値として追加し、JSONへのシリアライズ(その場合、ISO 8601形式に従って文字列として出力)まで保持できます。タイプが日付またはタイムスタンプのSQL値が追加された場合、is_Date
およびis_Timestamp
ファンクションはtrueを戻します。日付が文字列として(たとえば、ISO 8601として)追加された場合、is_Date
およびis_Timestamp
ファンクションはfalseを戻します。Oracle変換ファンクションto_Date
およびto_Timestamp
を使用して、日付およびタイムスタンプの文字列表現をOracle表現に変換できます。
エラー処理
JSON処理のエラー処理のレベルを設定できます。すべての不一致に対してエラーを生成する必要がないこともあります。on_Error
プロシージャを使用すると、どのような場合にエラーを生成するかを指定できます。
MEMBER PROCEDURE on_Error(value NUMBER)
on_Error
プロシージャは、PL/SQL操作(getコールなど)の間にエラーが検出された場合に実行する処理を定義します。
デフォルトでは、エラーを生成せずにNULLを戻します。
JSON_ELEMENT_TインスタンスでOn_error
を起動すると、それ以降のすべてのコールに対するエラー動作が設定されます。動作をデフォルトにリセットするには、on_Error(0)
をコールできます。
value
パラメータの値は、次のとおりです。
表282-1 ON_ERRORプロシージャのvalueパラメータの値
値 | 説明 |
---|---|
0 | デフォルト動作(エラーを生成せずにNULLを戻す)にリセットします。 |
1 | すべてのエラーを生成します。 |
2 | 値が検出されない場合、エラーを生成します。 |
3 | データ型が一致しない場合(たとえば、文字列値に対してGET_NUMBERをコールした場合など)にエラーを生成します。 |
4 | 入力が無効な場合(たとえば、配列が範囲外の場合など)にエラーを生成します。 |
値を組み合せることができます。たとえば、3と4の組合せを表す7を指定できます。
次の例では、"a"の値が"xyz"であるために数値に変換できず、エラーが生成されます。on_Error
プロシージャがコールされていない場合、NULLが戻されますが、エラーは生成されません。
declare jo JSON_OBJECT_T; begin jo := JSON_OBJECT_T.parse('{a:"xyz"}'); jo.On_error(1); dbms_output.put_line(jo.get_Number('a')); end; /
282.2 JSON_OBJECT_Tオブジェクト・タイプ
JSON_OBJECT_T
は、JSON_ELEMENT_Tオブジェクト・タイプのサブタイプです。これは、JSONのオブジェクト構造に対応しています。
コンストラクタ
次のコンストラクタを使用して、空のJSON_OBJECT_Tインスタンスを作成できます。
CONSTRUCTOR FUNCTION JSON_OBJECT_T RETURN SELF AS RESULT
次のいずれかのparse
ファンクションを使用して、JSON_OBJECT_Tインスタンスを作成できます。
STATIC FUNCTION parse(jsn VARCHAR2) RETURN JSON_OBJECT_T STATIC FUNCTION parse(jsn CLOB) RETURN JSON_OBJECT_T STATIC FUNCTION parse(jsn BLOB) RETURN JSON_OBJECT_T STATIC FUNCTION parse(jsn BLOB, FORMAT IN VARCHAR2) RETURN JSON_OBJECT_T
また、次のいずれかのコンストラクタを使用して、JSON_OBJECT_Tインスタンスを作成することもできます。
CONSTRUCTOR FUNCTION JSON_OBJECT_T(jsn VARCHAR2) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_OBJECT_T(jsn CLOB) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_OBJECT_T(jsn BLOB) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_Object_T(jsn BLOB, FORMAT IN VARCHAR2) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_OBJECT_T(jsn JSON) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_OBJECT_T(e JSON_ELEMENT_T) RETURN SELF AS RESULT
UTF8でエンコードされたJSONのみがBLOBとして渡されます。
parse
ファンクションは、入力としてJSON文字列を取り、JSONデータの内部表現を設定します。提供された入力が有効なJSONオブジェクトでない場合、エラー・メッセージが生成されます。入力は配列でなくJSONオブジェクトを指定する必要があります。
取得のファンクションおよびプロシージャ
次のファンクションおよびプロシージャを使用すると、JSONオブジェクトの値を取得できます。
MEMBER FUNCTION get(key VARCHAR2) RETURN JSON_ELEMENT_T MEMBER FUNCTION get_String(key VARCHAR2) RETURN VARCHAR2 MEMBER FUNCTION get_Number(key VARCHAR2) RETURN NUMBER MEMBER FUNCTION get_Date(key VARCHAR2) RETURN DATE MEMBER FUNCTION get_Timestamp(key VARCHAR2) RETURN TIMESTAMP MEMBER FUNCTION get_Boolean(key VARCHAR2) RETURN BOOLEAN MEMBER FUNCTION get_Clob(key VARCHAR2) RETURN CLOB MEMBER FUNCTION get_Blob(key VARCHAR2) RETURN BLOB MEMBER FUNCTION get_Object(key VARCHAR2) RETURN JSON_OBJECT_T MEMBER FUNCTION get_Array(key VARCHAR2) RETURN JSON_ARRAY_T MEMBER FUNCTION get_Json(key NUMBER) RETURN JSON MEMBER PROCEDURE get_Json(key NUMBER, j OUT NOCOPY JSON) MEMBER PROCEDURE get_Clob(key NUMBER, c IN OUT CLOB) MEMBER PROCEDURE get_Blob(key NUMBER, c IN OUT BLOB)
ノート:
-
get
ファンクションには参照セマンティクスがあります。つまり、戻されたJSON_ELEMENT_Tが変更されると、包含するJSON_ELEMENT_Tも変更されます。詳細は、次の項「参照セマンティクス」を参照してください。 -
GET_STRING
ファンクションは、まだ文字列でない値を文字列に変換します。したがって、IS_STRINGがfalseを戻した場合でも、GET_STRING
ファンクションはnullでない値を戻します。 -
すべてのgetファンクションは、可能な場合に変換を実行します。変換が可能でない場合、
ON_ERROR
の設定値に応じてエラーが生成されることがあります。
GET_CLOB
およびGET_BLOB
プロシージャは、CLOBまたはBLOBを入力として受け入れます。これによって、シリアライズの宛先として使用されるLOBを提供できます。たとえば、EMPTY_LOBを提供できます。このかわりにGET_CLOB
ファンクションを使用すると、新しいCLOBが暗黙的に作成されます。入力のLOBはNULLにできません。最初にBLOBまたはCLOBを作成しない場合は、GET_CLOBまたはGET_BLOBファンクションを使用できます。これらのファンクションはパラメータを取らずに、一時的なLOBを生成します。
GET_BLOB
は、UTF8形式へのシリアライズのみを行います。
設定のプロシージャ
次のプロシージャを使用すると、JSONオブジェクトの値を設定できます。値が存在する場合、その値は上書きされます。
MEMBER PROCEDURE put(key VARCHAR2, val JSON_ELEMENT_T) MEMBER PROCEDURE put(key VARCHAR2, val VARCHAR2) MEMBER PROCEDURE put(key VARCHAR2, val NUMBER) MEMBER PROCEDURE put(key VARCHAR2, val BOOLEAN) MEMBER PROCEDURE put(key VARCHAR2, val DATE) MEMBER PROCEDURE put(key VARCHAR2, val TIMESTAMP) MEMBER PROCEDURE put_Null(key VARCHAR2) MEMBER PROCEDURE put(key VARCHAR2, val JSON)
イントロスペクションのファンクション
イントロスぺクションを行うと、JSONオブジェクトを変更することなくJSONオブジェクトのプロパティを検出できます。イントロスペクションのファンクションは次のとおりです。
MEMBER FUNCTION has(key VARCHAR2) RETURN BOOLEAN MEMBER FUNCTION get_Type(key VARCHAR2) RETURN VARCHAR2 MEMBER FUNCTION get_Keys RETURN JSON_KEY_LIST
get_Keysファンクションは、JSON_KEY_LISTのオブジェクト・タイプ(VARCHAR2(4000)のVARRAY)を返します。このVARRAYには、JSONオブジェクトのキーの名前が含まれます。get_Keysファンクションは、指定されたJSONオブジェクトの最大32767個のフィールド名を返します。32767個を超えるフィールドを持つオブジェクトに適用されると、エラーが発生します。
次の例では、VARRAYのアイテムをウォークスルーして、すべてのキー名を含むJSON_ARRAY_Tオブジェクトを作成します。
declare jo JSON_OBJECT_T; ja JSON_ARRAY_T; keys JSON_KEY_LIST; keys_string VARCHAR2(100); begin ja := new JSON_ARRAY_T; jo := JSON_OBJECT_T.parse('{"name":"fred", "jobTitle":"codemonkey", "projects":["json", "xml"]}'); keys := jo.get_keys; for i in 1..keys.count loop ja.append(keys(i)); end loop; keys_string := ja.to_string; dbms_output.put_line(keys_string); end; /
出力は次のとおりです。
["name","jobTitle","projects"]
変更のプロシージャ
次のプロシージャを使用すると、JSONオブジェクトのキーを削除または名前変更できます。
MEMBER PROCEDURE remove(key VARCHAR2) MEMBER PROCEDURE rename_Key(keyOld VARCHAR2, keyNew VARCHAR2)
重複するキー名はサポートされておらず、エラーが発生します。
Cloneファンクション
このファンクションは、JSONオブジェクトのコピーを作成します。参照セマンティクスは値セマンティクスに変更されます。
MEMBER FUNCTION clone RETURN JSON_OBJECT_T
参照セマンティクス
JSON_ELEMENT_Tオブジェクトを戻すget
ファンクションをコールすると常に、コピーでなく複合値への参照が戻されます。つまり、戻された値を変更すると、そのコンテナに影響を与えます。次の例を参照してください。
declare data JSON_OBJECT_T; address JSON_OBJECT_T; zip number; begin data := new JSON_OBJECT_T('{ "first": "John", "last": "Doe", "address": { "country": "USA", "zip": "94065" } }'); address := data.get_object('address'); dbms_output.put_line(address.to_string); -- 1) VALUE SEMANTICS for scalar values -- (changing the value has no effect on container) zip := address.get_number('zip'); dbms_output.put_line(zip); zip := 12345; dbms_output.put_line(zip); -- address is still the same dbms_output.put_line(address.to_string); -- 2) REFERENCE SEMANTICS for complex values -- 'address' is a reference to the complex address values inside 'data' address.put('zip', 12345); address.put('street', 'Detour Road'); dbms_output.put_line(data.to_string); end; /
参照セマンティクスを使用しない場合は、clone
ファンクションを使用して、戻されたオブジェクトのコピーを作成できます。これにより、値がそのコンテナから切り離されます。前述の例でaddressオブジェクトのコピーを作成する場合、
address := data.get_object('address');
という行を、次の行で置き換えます。
address := data.get_object('address').clone;
これ以降は、アドレスを変更しても、データ包含オブジェクトの値に影響を与えません。
更新の例
次の例では、アイテムの価格を10%更新します。
WITH FUNCTION updatePrice(jsonTxt in VARCHAR2 ) RETURN VARCHAR2 IS jo JSON_OBJECT_T; oldPrice NUMBER; BEGIN jo := new JSON_OBJECT_T(jsonTxt); oldPrice := jo.get_number('price'); jo.put('price', oldPrice * 1.1); RETURN jo.to_string(); END; SELECT updatePrice(col) FROM t1;
282.3 JSON_ARRAY_Tオブジェクト・タイプ
JSON_ARRAY_T
は、JSON_ELEMENT_T
オブジェクト・タイプのサブタイプです。JSON_ARRAY_T
は、JSONの配列構造に対応しています。
コンストラクタ
次のコンストラクタを使用して、空のJSON_ARRAY_Tインスタンスを作成できます。
CONSTRUCTOR FUNCTION JSON_ARRAY_T RETURN SELF AS RESULT
次のいずれかのparse
ファンクションを使用して、JSON_ARRAY_Tインスタンスを作成できます。
STATIC FUNCTION parse(jsn VARCHAR2) RETURN JSON_ARRAY_T STATIC FUNCTION parse(jsn CLOB) RETURN JSON_ARRAY_T STATIC FUNCTION parse(jsn BLOB) RETURN JSON_ARRAY_T STATIC FUNCTION parse(jsn BLOB, FORMAT IN VARCHAR2) RETURN JSON_ARRAY_T
また、次のいずれかのコンストラクタを使用して、JSON_ARRAY_Tインスタンスを作成することもできます。
CONSTRUCTOR FUNCTION JSON_Array_T(jsn VARCHAR2) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_Array_T(jsn CLOB) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_Array_T(jsn BLOB) RETURN SELF AS RESULT CONSTRUCTOR FUNCTION JSON_Array_T(e JSON_ELEMENT_T) RETURN SELF AS RESULT
UTF8でエンコードされたJSONのみがBLOBとして渡されます。
parse
ファンクションは、入力としてJSON文字列を取り、JSONデータの内部表現を設定します。提供された入力が有効なJSONでない場合、エラー・メッセージが生成されます。入力はオブジェクトでなくJSON配列を指定する必要があります。
取得のファンクションおよびプロシージャ
次のファンクションおよびプロシージャを使用すると、JSON配列の値を取得できます。
MEMBER FUNCTION get(pos NUMBER) RETURN JSON_ELEMENT_T MEMBER FUNCTION get_String(pos NUMBER) RETURN VARCHAR2 MEMBER FUNCTION get_Number(pos NUMBER) RETURN NUMBER MEMBER FUNCTION get_Date(pos NUMBER) RETURN DATE MEMBER FUNCTION get_Timestamp(pos NUMBER) RETURN TIMESTAMP MEMBER FUNCTION get_Boolean(pos NUMBER) RETURN BOOLEAN MEMBER FUNCTION get_Clob(pos NUMBER) RETURN CLOB MEMBER FUNCTION get_Blob(pos NUMBER) RETURN BLOB MEMBER FUNCTION get_Json(pos NUMBER) RETURN JSON MEMBER PROCEDURE get_Json(pos NUMBER, j IN OUT NOCOPY JSON) MEMBER PROCEDURE get_Clob(pos NUMBER, c IN OUT CLOB) MEMBER PROCEDURE get_Blob(pos NUMBER, c IN OUT BLOB)
ノート:
-
get
ファンクションには参照セマンティクスがあります。つまり、戻されたJSON_ELEMENT_Tが変更されると、包含するJSON_ELEMENT_Tも変更されます。 -
GET_STRING
ファンクションは、まだ文字列でない値を文字列に変換します。IS_STRING
がfalseを戻した場合でも、このファンクションはnullでない値を戻します。 -
すべてのgetファンクションは、可能な場合に変換を実行します。変換が可能でない場合、
ON_ERROR
の設定値に応じてエラーが生成されることがあります。
GET_CLOB
およびGET_BLOB
プロシージャは、CLOB
またはBLOB
を入力として受け入れます。これによって、シリアライズの宛先として使用されるLOBを提供できます。たとえば、EMPTY_LOB
を提供できます。このかわりにGET_CLOB
ファンクションを使用すると、新しいCLOB
が暗黙的に作成されます。入力のLOB
はNULLにできません。最初にBLOB
またはCLOB
を作成しない場合は、GET_CLOB
またはGET_BLOB
ファンクションを使用できます。これらのファンクションはパラメータを取らずに、一時的なLOBを生成します。
GET_BLOB
は、UTF8形式へのシリアライズのみを行います。
設定のプロシージャ
次のプロシージャを使用すると、JSON配列内の指定した位置に値を設定できます。これらのプロシージャでは、上書きがリクエストされないかぎり、指定された位置で(上書きではなく)挿入が行われます。
MEMBER PROCEDURE put(pos NUMBER, val VARCHAR2, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val NUMBER, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val BOOLEAN, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val DATE, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val JSON_ELEMENT_T, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val JSON, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put(pos NUMBER, val TIMESTAMP, overwrite BOOLEAN DEFAULT FALSE) MEMBER PROCEDURE put_Null(pos NUMBER, overwrite BOOLEAN DEFAULT FALSE)
次のプロシージャは、指定された値をJSON配列の末尾に追加します。
MEMBER PROCEDURE append(val JSON_ELEMENT_T) MEMBER PROCEDURE append(val VARCHAR2) MEMBER PROCEDURE append(val NUMBER) MEMBER PROCEDURE append(val BOOLEAN) MEMBER PROCEDURE append(val DATE) MEMBER PROCEDURE append(val JSON) MEMBER PROCEDURE append(val TIMESTAMP) MEMBER PROCEDURE append_Null
イントロスペクションのファンクション
イントロスぺクションを行うと、JSON配列を変更することなくJSON配列のプロパティを検出できます。
MEMBER FUNCTION get_Type(pos NUMBER) RETURN VARCHAR2
変更のプロシージャ
次のプロシージャを使用すると、JSON配列内の指定した位置にある値を削除できます。
MEMBER PROCEDURE remove(pos NUMBER)
Cloneファンクション
このファンクションは、JSON配列のコピーを作成します。参照セマンティクスは値セマンティクスに変更されます。
MEMBER FUNCTION clone RETURN JSON_ARRAY_T
282.4 JSON_SCALAR_Tオブジェクト・タイプ
JSON_SCALAR_T
は、JSON_ELEMENT_T
オブジェクト・タイプのサブタイプです。
説明
JSON_SCALAR_T
インスタンスは、1つのスカラー値(たとえば、文字列fred、数値1など)を取得します。このタイプには、JSON_ELEMENT_T
から継承されたもの以外のファンクションまたはプロシージャはありません。このタイプのインスタンスを直接作成することはできません。
282.5 JSON_KEY_LISTタイプ
JSON_KEY_LIST
は、VARCHAR2(4000)
のVARRAYです。
説明
このタイプは、JSON_OBJECT_Tオブジェクト・タイプのget_Keys
ファンクションによって使用されます。