20 JSON用のPL/SQLオブジェクト型の概要
PL/SQLオブジェクト型を使用すると、インメモリーJSONデータをプログラム的に細かく構成および操作できます。テキストのJSONデータに戻って、イントロスペクション、変更およびシリアライズを行えます。
主なPL/SQL JSONオブジェクト型には、JSON_ELEMENT_T
、JSON_OBJECT_T
、JSON_ARRAY_T
およびJSON_SCALAR_T
があります。この他にも、使用頻度が比較的少ないオブジェクト型としてJSON_KEY_LIST
があります。これは、VARCHAR2(4000)
のVARRAYです。オブジェクト型は、抽象データ型(ADT)とも呼ばれます。
これらのJSONオブジェクト型は、データベース内に格納されたJSONデータのインメモリーで(ツリーのような)階層型のプログラム的表現を提供します。脚注1
次のことを行うために、オブジェクト型を使用してJSONデータをインメモリーでプログラム的に操作できます。
-
既存のJSONデータの構造、型または値をチェックします。たとえば、指定したオブジェクト・フィールドの値が特定の条件を満たしているかどうかをチェックします。
-
既存のJSONデータを変換します。たとえば、住所や電話番号の形式を特定の形式に従うように変換します。
-
データが表す特性に一致するプログラミング・ルールを使用して、JSONデータを作成します。たとえば、JSONオブジェクトとして表す製品が可燃性のあるものだった場合に、安全情報を表すフィールドを含めます。
PL/SQLオブジェクト型インスタンスは一時的です。ここに含まれる情報を永続的に格納するには、VARCHAR2
またはLOBデータにそれらをシリアル化する必要があります。これらをデータベース表またはJava Database Connectivity (JDBC)などのデータベース・クライアントへのマーシャルに格納できます。
インメモリーでのオブジェクト型インスタンスの構成は、JSONテキストを解析することで一括して行うか、空のオブジェクトまたは配列インスタンスから始めてそこにオブジェクト・メンバーまたは配列要素を追加することで段階的に行うかのいずれかの方法で実施します。
使用されていないオブジェクト型インスタンスは自動的なガベージ・コレクションによって処理されるため、必要なくなったインスタンスで使用されたメモリーの解放は行うことができず、その必要もありません。
通常は、PL/SQLオブジェクト型インスタンスを構成し、おそらく様々な方法でプログラム的に利用した後で、VARCHAR2
、CLOB
またはBLOB
のデータ型のインスタンスにシリアライズします。つまり、インメモリーのJSONデータの一時的な表現を、データベースの永続的な表現に変換します。(または、出力のためのテキストとしてのみシリアライズする場合もあります。)
JSONオブジェクト型の相互関係
型JSON_ELEMENT_T
は、他のJSONオブジェクト型のスーパータイプです。各JSONオブジェクト型がサブタイプとしてこれを拡張します。サブタイプJSON_OBJECT_T
およびJSON_ARRAY_T
は、それぞれJSONオブジェクトと配列に対して使用されます。サブタイプJSON_SCALAR_T
は、スカラーJSON値である文字列、数値、ブール値のtrue
およびfalse
、値null
で使用されます。
型JSON_ELEMENT_T
のインスタンスは、JSONテキストの解析によってのみ構成できます。解析によって、JSONデータのインメモリー表現である、JSON_ELEMENT_T
インスタンスが作成されます。型がJSON_ELEMENT_T
または型JSON_SCALAR_T
の空のインスタンスは構成できません。
型JSON_OBJECT_T
とJSON_ARRAY_T
には、型と同じ名前のコンストラクタ関数があり、それぞれJSONオブジェクトまたは配列の空の(インメモリー)表現のインスタンスをその型で構成するために使用できます。その後、PL/SQLオブジェクト型インスタンスとして表されるオブジェクト・メンバーまたは配列要素を追加して、必要に応じてこのオブジェクトまたは配列にデータを入力できます。
PL/SQLファンクションtreat
を使用して、JSON_ELEMENT_T
のインスタンスをサブタイプ・インスタンスにキャストできます。たとえば、treat(elt as JSON_OBJECT_T)
はインスタンスelt
をJSONオブジェクト(JSON_OBJECT_T
のインスタンス)としてキャストします。
解析関数
静的関数parse
には、引数としてVARCHAR2
、CLOB
またはBLOB
の型のインスタンスを指定できます。この関数は、各インスタンスをJSONテキストとして解析し、JSON_ELEMENT_T
、JSON_OBJECT_T
またはJSON_ARRAY_T
型のインスタンスを戻します。
シリアライズ・メソッド
解析では、入力のJSONデータをテキストとして受け入れ、PL/SQL JSONオブジェクト型のインスタンスを戻します。シリアライズでは、基本的に反対のことが行われます。JSONデータのPL/SQLオブジェクト表現にシリアライズを適用すると、そのオブジェクトのテキスト表現が戻されます。シリアライズ・メソッドの名前は、接頭辞to_
から始まります。たとえば、メソッドto_string()
をJSONオブジェクト型のインスタンスに適用すると、そのインスタンスの文字列(VARCHAR2
)表現が戻されます。
ほとんどのシリアライズ・メソッドはメンバ関数です。ただし、CLOB
またはBLOB
インスタンスとしてのシリアライズの場合は、メンバ関数とメンバー・プロシージャの2つの形式のメソッドがあります。メンバ関数は、引数を受け入れません。この場合は、シリアライズの宛先として一時的なLOBが作成されます。メンバー・プロシージャはLOB IN OUT
引数を受け入れます(メソッドto_clob
の場合はCLOB
インスタンス、メソッドto_blob
の場合はBLOB
)。このように、シリアライズされた表現に使用するLOB (空の可能性もある)に渡します。
getterメソッドとsetterメソッド
型JSON_OBJECT_T
およびJSON_ARRAY_T
には、getterメソッドとsetterメソッドがあります。これらはそれぞれ、特定のオブジェクト・フィールドの値、または特定の配列要素の位置の値を取得および更新します。
getterメソッドには2つの種類があります。
-
メソッド
get()
は、メソッドを適用した元のオブジェクトへの参照を、型JSON_ELEMENT_T
のインスタンスとして戻します。つまり、メソッドの適用対象のオブジェクトは参照渡しされます。その後、戻されたJSON_ELEMENT_T
インスタンスを変更した場合、変更内容はget()
を適用した元のオブジェクトに適用されます。 -
メソッド名に接頭辞
get_
が付くgetterメソッドは、適用されたオブジェクトまたは配列内で対象となった任意のデータのコピーを戻します。このデータは参照されるのではなく、値によって渡されます。たとえば、メソッド
get_string()
をJSON_OBJECT_T
インスタンスに適用した場合、指定されたフィールドを引数として渡すと、そのフィールドの値の文字列のコピーが戻されます。get_string()
をJSON_ARRAY_T
インスタンスに適用した場合は、指定した要素の位置を引数として渡すと、配列内のその位置にある文字列のコピーを戻します。
シリアライズ・メソッドと同様に、ほとんどのgetterメソッドはメンバ関数です。ただし、指定したオブジェクト・フィールドの値か、指定した配列の位置にある要素をCLOB
またはBLOB
インスタンスとして戻すget_clob()
およびget_blob()
のメソッドには、(シリアライズ・メソッドto_clob()
およびto_blob()
のように)メンバ関数とメンバー・プロシージャの2つの形式があります。メンバ関数は、対象となるオブジェクト・フィールドまたは配列の位置以外の引数は受け入れません。一時LOBインスタンスを作成して戻します。メンバー・プロシージャはLOB IN OUT
引数も受け入れます(get_clob
の場合はCLOB
、get_blob
の場合はBLOB
)。このように、メンバー・プロシージャを使用する(空の可能性もある)LOBインスタンスに渡すことができます。
setterメソッドは、put()
、put_null()
および(JSON_ARRAY_T
のみについては)append()
です。これらのメソッドは、対象のオブジェクト・フィールドまたは配列要素の値を設定して、適用されたオブジェクトまたは配列のインスタンスを更新します。注意: setterメソッドは、変更されたインスタンスのコピーを戻すかわりに、既存のインスタンスを変更します。
メソッドappend()
は、配列インスタンスの末尾に新しい要素を追加します。メソッドput_null()
は、オブジェクト・フィールドまたは配列要素の値をJSON null
に設定します。
メソッドput()
では、2つ目の引数に設定する新しい値を指定する必要があります(オブジェクト・フィールド名または配列要素の位置の他に)。配列の場合は、put()
は、オプションで3つ目の引数OVERWRITE
も受け入れます。これは、BOOLEAN
値で(デフォルトはFALSE
)、指定された位置にある既存の値を置換するかどうかを示します。
-
オブジェクトに、同じ名前のフィールドがすでにある場合、
put()
はその値を置き換えて新しい値にします。 -
配列の指定された位置に要素がすでにあった場合は、デフォルトの動作として、
put()
はその要素とそれに続くすべての要素を先に移動させ(それらの位置を1つずつインクリメントして)、新しい要素のためのスペースを作成します。これで、新しい要素が指定された位置に配置されます。ただし、オプションの引数OVERWRITE
が指定されていてTRUE
の場合、指定された位置の既存の要素は、単純に新しい要素で置き換えられます。
イントロスペクション・メソッド
型JSON_ELEMENT_T
には、インスタンスがJSONオブジェクト、配列、スカラー、文字列、数値またはブール値かどうか、またはJSON値true
、false
またはnull
であるかどうかを判断するために使用できる、イントロスペクション・メソッドがあります。これらのメソッドの名前は、接頭辞is_
で始まります。これらは、BOOLEAN
値を戻す述語です。
この型には、イントロスペクション・メソッドget_size()
もあります。これは、JSON_OBJECT_T
インスタンスのメンバーの数と、JSON_ARRAY_T
インスタンスの要素数を戻します(JSON_SCALAR_T
インスタンスに対して1を戻します)。
型JSON_ELEMENT_T
には、イントロスペクション・メソッドis_date()
とis_timestamp()
もあります。これらは、インスタンスが日付またはタイムスタンプを表すかどうかをテストします。JSONには、日付またはタイムスタンプのネイティブ・タイプはありません。これらは、通常、JSON文字列を使用して表されています。ただし、JSON_ELEMENT_T
インスタンスが、SQLデータ型DATE
またはTIMESTAMP
のSQLデータを使用して構成されている場合、この型情報は、PL/SQLのオブジェクト表現用に保持されます。
日付とタイムスタンプのデータは、PL/SQLオブジェクト型JSON_SCALAR_T
を使用して表されます。この型のインスタンスは、直接構成することはできません。ただし、このような値をオブジェクト(フィールド値として追加)または配列(要素として)にメソッドput()
を使用して追加できます。メソッドget()
を使用してこれを取得すると、JSON_SCALAR_T
インスタンスが戻されます。
型JSON_OBJECT_T
およびJSON_ARRAY_T
には、イントロスペクション・メソッドget_type()
があります。これは、対象となるオブジェクト・フィールドまたは配列要素のJSON型を戻します(VARCHAR2
インスタンスとして)。また、型JSON_OBJECT_T
には2つのイントロスペクション・メソッドがあります。has()
は、オブジェクトに指定された名前のフィールドがすでにある場合はTRUE
を戻します。また、get_keys()
は、PL/SQLオブジェクト型JSON_KEY_LIST
のインスタンスを戻します。これは、VARCHAR2(4000)
のVARRAYです。VARRAYには、指定されたJSON_OBJECT_T
インスタンスにあるフィールドFoot 2 Footref 2の名前が含まれます。
その他のメソッド
型JSON_OBJECT_T
およびJSON_ARRAY_T
には、次のメソッドがあります。
-
remove()
: 指定されたフィールドまたは指定された位置の配列要素を持つオブジェクト・メンバーを削除します。 -
clone()
: メソッドが適用されるオブジェクトまたは配列の(ディープ)コピーを作成および戻します。このコピーを変更しても、元のオブジェクトまたは配列に影響はありません。
型JSON_OBJECT_T
にはメソッドrename_key()
があります。これは、指定されたオブジェクト・フィールドの名前を変更します。Footref 2指定された新しい名前が既存のフィールドの名前だった場合は、エラーが発生します。
関連項目:
-
JSON_ARRAY_T
の詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください。 -
JSON_ELEMENT_T
の詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください。 -
JSON_OBJECT_T
およびJSON_KEY_LIST
の詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください。 -
JSON_SCALAR_T
の詳細は、Oracle Database PL/SQLパッケージおよびタイプ・リファレンスを参照してください。
親トピック: JSON用のPL/SQLオブジェクト型
脚注の凡例
脚注1: これは、Document Object Model (DOM)を使用してXMLデータで使用可能なものと類似しています。DOMは、言語やプラットフォームに依存しないオブジェクト・モデルおよびAPIで、XMLドキュメントの構造へのアクセス用にWorld Wide Web Consortium (W3C)から推奨されています。脚注2: オブジェクト・フィールドは、オブジェクトの「キー」と呼ばれることもあります。