182 DBMS_SODA
DBMS_SODAパッケージは、Simple Oracle Document Access (SODA)を実装するPL/SQLパッケージです。 SODAにより、Oracle DatabaseをNoSQLドキュメント・ストアとして使用できます。 SODAが提供している主要な抽象化は、ドキュメント・コレクションの抽象化です。 DBMS_SODAパッケージを使用すると、PL/SQLからドキュメント・コレクションを作成、リストおよび削除し、ドキュメントに対してCRUD (作成、置換、更新、削除)操作を実行できます。 すべてのDDLファンクションがこのパッケージ内にカプセル化されています。
この章のトピックは、次のとおりです:
182.1 DBMS_SODAのセキュリティ・モデル
このパッケージは、SODA_APPロールを持つユーザーが使用できます。
すべてのSODAタイプ(パッケージおよびタイプ)は、SYSタイプです。 PUBLICには、この章で説明するDBMS_SODAに対するEXECUTE権限が付与されます。
182.2 DBMS_SODAサブプログラムの要約
この表は、DBMS_SODAサブプログラムをアルファベット順に示し、簡単に説明しています。
表182-1 DBMS_SODAパッケージ・サブプログラム
| サブプログラム | 用途 |
|---|---|
|
コレクション名およびメタデータを使用してコレクションを作成します。 |
|
|
ユーザーのスキーマから既存のコレクションを削除します。 これにより、コレクション内のすべてのドキュメントも削除されます。 |
|
|
このファンクションは、現行データベースのSCN番号を戻します。 |
|
|
このファンクションは、現在のデータベース・タイムスタンプ値を戻します。 |
|
|
このファンクションは、デフォルトのメタデータを戻します。 |
|
|
このファンクションは、デフォルトのメタデータを戻します。 |
|
|
ユーザーのスキーマ内のコレクション名を |
|
|
既存のコレクションをオープンします。 |
182.2.1 CREATE_COLLECTIONファンクション
コレクション名およびメタデータを使用してコレクションを作成します。 メタデータで指定されている設定を使用し、指定されていない設定を自動的に割り当て、コレクション・オブジェクトを戻します。 metadata引数が省略されている場合、またはNULLに設定されている場合、コレクションはデフォルトのメタデータを使用して作成されます。 戻されたコレクションは、readまたはwrite操作(あるいはその両方)用にオープンされます。 コレクションがすでに存在する場合、ファンクションは単にコレクション・オブジェクトをオープンして戻します。
構文
DBMS_SODA.CREATE_COLLECTION (
collection_Name IN NVARCHAR2,
metadata IN VARCHAR2 DEFAULT NULL,
create_Mode IN PLS_INTEGER DEFAULT CREATE_MODE_DDL)
RETURN SODA_Collection_T;パラメータ
表182-2 CREATE_COLLECTIONパラメータ
| パラメータ | 説明 |
|---|---|
|
|
コレクションの名前。
|
|
|
|
|
create_Mode |
有効な値は、次のとおりです。
|
戻り値
このファンクションは、コレクションを表すSoda_Collection_Tオブジェクトを戻します。
例外
-
Descriptor Error- 入力記述子が無効な場合 -
Error- コレクションの作成中にエラーが発生した場合
182.2.2 DROP_COLLECTIONファンクション
ユーザーのスキーマから既存のコレクションを削除します。 これにより、コレクション内のすべてのドキュメントも削除されます。
構文
DBMS_SODA.DROP_COLLECTION (
collection_Name IN NVARCHAR2,
purge IN BOOLEAN DEFAULT FALSE,
drop_Mapped_Table IN BOOLEAN DEFAULT FALSE)
RETURN NUMBER;
パラメータ
表182-3 DROP_COLLECTIONパラメータ
| パラメータ | 説明 |
|---|---|
|
|
コレクションの名前。
|
|
|
デフォルト値は |
|
|
デフォルト値は |
戻り値
この関数は、次の値を返します。
-
1- コレクションが正常に削除された場合 -
0- コレクションが存在しない場合
例外
コレクションへのコミットされていない書込みや権限の問題などによって、コレクションの削除中にエラーが発生した場合。
182.2.3 GET_AS_OF_SCNファンクション
このファンクションは、現行データベースのSCN番号を戻します。
構文
DBMS_SODA.GET_AS_OF_SCN ( ) RETURN NUMBER;
戻り値
このファンクションは、現行データベースのSCN番号を戻します。
182.2.4 GET_AS_OF_TIMESTAMPファンクション
このファンクションは、現在のデータベース・タイムスタンプ値を戻します。
構文
DBMS_SODA.GET_AS_OF_TIMESTAMP ( ) RETURN VARCHAR2;
戻り値
このファンクションは、現在のデータベース・タイムスタンプ値を戻します。
182.2.5 GET_DEFAULT_METADATA_AS_CLOBファンクション
このファンクションは、デフォルトのメタデータを戻します。
構文
DBMS_SODA.GET_DEFAULT_METADATA_AS_CLOB ( ) RETURN CLOB;
戻り値
このファンクションは、CLOBデータ・タイプを使用してデフォルトのメタデータを戻します。
182.2.6 GET_DEFAULT_METADATA_AS_VARCHAR2ファンクション
このファンクションは、デフォルトのメタデータを戻します。
構文
DBMS_SODA.GET_DEFAULT_METADATA_AS_VARCHAR2 ( ) RETURN VARCHAR2;
戻り値
このファンクションは、VARCHAR2データ・タイプを使用してデフォルトのメタデータを戻します。
182.2.7 LIST_COLLECTION_NAMESファンクション
このファンクションは、ユーザーのスキーマ内のコレクション名のリストをNVARCHAR2の表として戻します。
構文
DBMS_SODA.LIST_COLLECTION_NAMES () RETURN SODA_CollName_List_T;
戻り値
このファンクションは、コレクション名のリストをNVARCHAR2(255)の表として戻します。 スキーマ内にコレクションがない場合、コレクション・リストは空になります。
例外
Error - コレクション名のリストを作成しているときにエラーが発生した場合。
182.2.8 OPEN_COLLECTIONファンクション
readまたはwrite操作(あるいはその両方)用に既存のコレクションをオープンします。
構文
DBMS_SODA.OPEN_COLLECTION (
collection_Name IN NVARCHAR2)
RETURN SODA_Collection_T;
パラメータ
表182-4 OPEN_COLLECTIONパラメータ
| パラメータ | 説明 |
|---|---|
|
|
コレクションの名前。
|
戻り値
この関数は、次の値を返します。
-
オープンしているコレクション・オブジェクト
-
ファイルが存在しない場合は
NULL
例外
Error - コレクションの作成中にエラーが発生した場合
182.3 SODAオンライン再定義サブプログラムの要約
この表は、SODAオンライン再定義サブプログラムをアルファベット順に示し、簡単に説明しています。
表182-5 SODAオンライン再定義サブプログラム
| サブプログラム | 用途 |
|---|---|
|
このプロシージャは、 |
|
|
このプロシージャは、データ表を再定義できるかどうかをチェックします。 データ表を再定義できない場合は、エラーが発生します。 |
|
|
このプロシージャは、元の表に定義されているすべての依存を仮表にコピーします。 ただし、仮表がJSON型の場合、 |
|
|
このプロシージャは、仮の |
|
|
このプロシージャは、1つのアトミック・トランザクションで次のタスクを実行します。 それにより、停止時間が発生します。 これは、 |
|
|
このプロシージャは、再定義プロセスを開始します。 元の表から仮表に既存のデータをコピーし、再定義された列に対して必要な変換を実行します。 |
|
|
このプロシージャは、元のデータ表が変更された場合に、変更内容を仮表に同期します。 このプロシージャは、 |
|
| TO_UUIDファンクション |
このファンクションは、データ・ポンプ・インポート中に、コレクション表のバージョン列をUUID値に再マップするために使用します。 このファンクションは、データ・ポンプの |
182.3.1 ABORT_REDEF_COLLECTIONプロシージャ
このプロシージャは、CREATE_INTERIM_COLLECTION、START_REDEF_COLLECTION、COPY_COLLECTION_DEPENDENTS、SYNC_INTERIM_COLLETIONまたはその他の理由でエラーが発生した場合に、コレクションに加えられた変更を元に戻します。
構文
DBMS_SODA.ABORT_REDEF_COLLECTION ( collection_name IN NVARCHAR2, interim_collection_name IN NVARCHAR2);
パラメータ
表182-6 ABORT_REDEF_COLLECTIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
|
|
仮のコレクションに使用する名前。 |
182.3.2 CAN_REDEF_COLLECTIONプロシージャ
このプロシージャは、データ表を再定義できるかどうかをチェックします。 データ表を再定義できない場合は、エラーが発生します。
構文
DBMS_SODA.CAN_REDEF_COLLECTION ( collection_name IN NVARCHAR2);
パラメータ
表182-7 CAN_REDEF_COLLECTIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
182.3.3 COPY_COLLECTION_DEPENDENTSプロシージャ
このプロシージャは、元の表に定義されているすべての依存を仮表にコピーします。
構文
DBMS_SODA.COPY_COLLECTION_DEPENDENTS ( collection_name IN NVARCHAR, interim_collection_name IN NVARCHAR2, ignore_error IN BOOLEAN DEFAULT NULL, num_errors OUT PLS_INTEGER);
パラメータ
表182-8 COPY_COLLECTION_DEPENDENTSプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
interim_collection_name |
仮のコレクションに使用する名前。 |
ignore_error |
処理で発生したエラーを無視して続行します。 |
num_errors |
処理中に発生したエラー数。 |
182.3.4 CREATE_INTERIM_COLLECTIONプロシージャ
このプロシージャは、仮のSODAコレクションを作成します。 interim_metadataは、ユーザーが行う必要がある変更を指定します。 たとえば、元のメタデータへのパッチとして適用されるデルタです。
構文
DBMS_SODA.CREATE_INTERIM_COLLECTION ( collection_name IN NVARCHAR2, interim_collection_name IN NVARCHAR2, interim_metadata IN VARCHAR2);
パラメータ
表182-9 CREATE_INTERIM_COLLECTIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
interim_collection_name |
仮のコレクションに使用する名前。 |
interim_metadata |
再定義する必要がある列とその再定義方法を指定するメタデータ・スニペット。 |
使用上のノート
interim_metadataパラメータには、次のフィールドを含めることができます。 他のフィールドが存在し、それらのフィールドが元のコレクションのメタデータのフィールドと同じではない場合には、エラーが発生します。
contentColumn.sqlTypeをJSONに設定してCONTENT列をJSON型で再定義すると、必要に応じて、VERSION列が自動的に生成されます。versionColumn.methodをUUIDに設定して、UUIDを使用するようにVERSION列を再定義します。tableNameを設定して、この仮のコレクションのデータ表の名前を指定します。 このフィールドが存在しない場合は、コレクション表のデフォルトのネーミングで説明されているデフォルトの表名のルールに従って、デフォルトのデータ表名が生成されます。 ただし、表がすでに存在する場合、コレクションはMAPモードを使用して作成されます。 このシナリオでは、マップされる表に制約が定義されていないことを確認します。- ユーザーは、指定した
interim_metadataスニペットで前述のフィールドを組み合せることができます。 たとえば、最も一般的なユースケースは、コンテンツ列をJSON型に再定義し、バージョン列をUUIDに再定義することです。これは、interim_metadataパラメータを{“contentColumn” : {“sqlType”: “JSON”}, “versionColumn” : {“method”: “UUID”}}に設定して行うことができます。
182.3.5 FINISH_REDEF_COLLECTIONプロシージャ
このプロシージャは、1つのアトミック・トランザクションで次のタスクを実行します。 それにより、停止時間が発生します。 これは、SODAデータ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。
構文
DBMS_SODA.FINISH_REDEF_COLLECTION ( collection_name IN NVARCHAR, interim_collection_name IN NVARCHAR2, dml_lock_timeout IN PLS_INTEGER DEFAULT NULL);
パラメータ
表182-10 FINISH_REDEF_COLLECTIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
interim_collection_name |
仮のコレクションに使用する名前。 |
dml_lock_timeout |
待機時間(秒)。 この待機時間内にロックが取得されない場合は、エラーが発生します。 |
使用上のノート
このアクションは元に戻すことができません。 このプロシージャの実行後、DBMS_REDEFINITIONパッケージで提供されるROLLBACKプロシージャを実行することはできません。
注意:
FINISH_REDEF_COLLECTIONプロシージャをコールする前に、仮のコレクションを試して、仮のコレクションにアクセスできることと、それが期待どおりに機能することを確認する必要があります。 問題が発生した場合は、ABORT_REDEF_COLLECTIONプロシージャを使用してください。
これは、FINISH_REDEF_COLLECTIONをコールする前に行うことが非常に重要です。FINISH_REDEF_COLLECTIONを元に戻すことはできないためです。
182.3.6 START_REDEF_COLLECTIONプロシージャ
このプロシージャは、再定義プロセスを開始します。 元の表から仮表に既存のデータをコピーし、再定義された列に対して必要な変換を実行します。
構文
DBMS_SODA.START_REDEF_COLLECTION ( collection_name IN NVARCHAR, interim_collection_name IN NVARCHAR2, copy_vpd_opt IN DEFAULT NULL, refresh_dep_mviews IN DEFAULT NULL);
パラメータ
表182-11 START_REDEF_COLLECTIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
interim_collection_name |
仮のコレクションに使用する名前。 |
copy_vpd_opt |
|
refresh_dep_mviews |
|
182.3.7 SYNC_INTERIM_COLLETIONプロシージャ
このプロシージャは、元のデータ表が変更された場合に、変更内容を仮表に同期します。 このプロシージャは、SODAデータ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。
構文
DBMS_SODA.SYNC_INTERIM_COLLETION ( collection_name IN NVARCHAR, interim_collection_name IN NVARCHAR2);
パラメータ
表182-12 SYNC_INTERIM_COLLETIONプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
再定義するコレクションの名前。 |
interim_collection_name |
仮のコレクションに使用する名前。 |
182.3.8 TO_UUIDファンクション
このファンクションは、データ・ポンプ・インポート中に、コレクション表のバージョン列をUUID値に再マップするために使用します。 このファンクションは、データ・ポンプのREMAP_DATA機能でのみ使用します。
構文
DBMS_SODA.TO_UUID (
placeholder IN NVARCHAR2)
RETURN VARCHAR2;
パラメータ
表182-13 TO_UUIDパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このパラメータは、使用されていないため、無視しても問題ありません。 これが使用されるのは、データ・ポンプの |
戻り値
このファンクションは、UUID値として使用できる16進数の文字列を戻します。
参照:
Oracle® Databaseユーティリティ・ガイドのREMAP_DATA。