DBMS_SODA

153 DBMS_SODA

DBMS_SODAパッケージは、Simple Oracle Document Access (SODA)を実装するPL/SQLパッケージです。SODAにより、Oracle DatabaseをNoSQLドキュメント・ストアとして使用できます。SODAが提供している主要な抽象化は、ドキュメント・コレクションの抽象化です。DBMS_SODAパッケージを使用すると、PL/SQLからドキュメント・コレクションを作成、リストおよび削除し、ドキュメントに対してCRUD (作成、置換、更新、削除)操作を実行できます。すべてのDDLファンクションがこのパッケージ内にカプセル化されています。

この章のトピックは、次のとおりです:

参照:

153.1 DBMS_SODAのセキュリティ・モデル

このパッケージは、SODA_APPロールを持つユーザーが使用できます。

すべてのSODAタイプ(パッケージおよびタイプ)は、SYSタイプです。PUBLICには、この章で説明するDBMS_SODAに対するEXECUTE権限が付与されます。

153.2 DBMS_SODAサブプログラムの要約

この表は、DBMS_SODAサブプログラムをアルファベット順に示し、簡単に説明しています。

表153-1 DBMS_SODAパッケージのサブプログラム

サブプログラム	用途
CREATE_COLLECTIONファンクション	コレクション名およびメタデータを使用してコレクションを作成します。
DROP_COLLECTIONファンクション	ユーザーのスキーマから既存のコレクションを削除します。これにより、コレクション内のすべてのドキュメントも削除されます。
LIST_COLLECTION_NAMESファンクション	ユーザーのスキーマ内のコレクション名を`NVARCHAR2`の表としてリストします。
OPEN_COLLECTIONファンクション	既存のコレクションをオープンします。

153.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;

パラメータ

表153-2 CREATE_COLLECTIONのパラメータ

パラメータ説明

パラメータ	説明
`collection_Name`	コレクションの名前。 `collection_Name`の値は、大/小文字が区別されます。
`metadata`	`VARCHAR2`形式のコレクションのメタデータ。
create_Mode	有効な値は、次のとおりです。 `DBMS_SODA.CREATE_MODE_DDL` (デフォルト)。最初にコレクション用の新しい表を作成しようとします。すでに表が存在する場合は、既存の表をコレクションにマップしようとします。最小限のチェックが実行され、表の形状が指定されたコレクション・メタデータと一致することを確認します(一致しない場合は、エラーが返されます)。 `DBMS_SODA.CREATE_MODE_MAP`。既存の表をコレクションにマップしようとします。最小限のチェックが実行され、表の形状が指定されたコレクション・メタデータと一致することを確認します(一致しない場合は、エラーが返されます)。

collection_Name

コレクションの名前。

collection_Nameの値は、大/小文字が区別されます。

metadata

VARCHAR2形式のコレクションのメタデータ。

create_Mode

有効な値は、次のとおりです。

DBMS_SODA.CREATE_MODE_DDL (デフォルト)。最初にコレクション用の新しい表を作成しようとします。すでに表が存在する場合は、既存の表をコレクションにマップしようとします。最小限のチェックが実行され、表の形状が指定されたコレクション・メタデータと一致することを確認します(一致しない場合は、エラーが返されます)。
DBMS_SODA.CREATE_MODE_MAP。既存の表をコレクションにマップしようとします。最小限のチェックが実行され、表の形状が指定されたコレクション・メタデータと一致することを確認します(一致しない場合は、エラーが返されます)。

戻り値

このファンクションは、コレクションを表すSoda_Collection_Tオブジェクトを戻します。

例外

Descriptor Error - 入力記述子が無効な場合
Error - コレクションの作成中にエラーが発生した場合

参照:

Oracle Database PL/SQLのためのSODA開発者ガイド

153.2.2 DROP_COLLECTIONファンクション

ユーザーのスキーマから既存のコレクションを削除します。これにより、コレクション内のすべてのドキュメントも削除されます。

構文

DBMS_SODA.DROP_COLLECTION (
     collection_Name      IN NVARCHAR2)
 RETURN NUMBER;

パラメータ

表153-3 DROP_COLLECTIONのパラメータ

パラメータ説明

パラメータ	説明
`collection_Name`	コレクションの名前。 `collection_Name`の値は、大/小文字が区別されます。

collection_Name

コレクションの名前。

collection_Nameの値は、大/小文字が区別されます。

戻り値

この関数は、次の値を返します。

1 - コレクションが正常に削除された場合
0 - コレクションが存在しない場合

例外

コレクションへのコミットされていない書込みや権限の問題などによって、コレクションの削除中にエラーが発生した場合。

参照:

Oracle Database PL/SQLのためのSODA開発者ガイド

153.2.3 LIST_COLLECTION_NAMESファンクション

このファンクションは、ユーザーのスキーマ内のコレクション名のリストをNVARCHAR2の表として戻します。

構文

DBMS_SODA.LIST_COLLECTION_NAMES ()
 RETURN SODA_CollName_List_T;

戻り値

このファンクションは、コレクション名のリストをNVARCHAR2(255)の表として戻します。スキーマ内にコレクションがない場合、コレクション・リストは空になります。

例外

Error - コレクション名のリストを作成しているときにエラーが発生した場合。

参照:

Oracle Database PL/SQLのためのSODA開発者ガイド

153.2.4 OPEN_COLLECTIONファンクション

readまたはwrite操作(あるいはその両方)用に既存のコレクションをオープンします。

構文

DBMS_SODA.OPEN_COLLECTION (
     collection_Name      IN NVARCHAR2)
 RETURN SODA_Collection_T;

パラメータ

表153-4 OPEN_COLLECTIONのパラメータ

パラメータ説明

パラメータ	説明
`collection_Name`	コレクションの名前。 `collection_Name`の値は、大/小文字が区別されます。

collection_Name

コレクションの名前。

collection_Nameの値は、大/小文字が区別されます。

戻り値

この関数は、次の値を返します。

オープンしているコレクション・オブジェクト
ファイルが存在しない場合はNULL

例外

Error - コレクションの作成中にエラーが発生した場合

参照:

153.3 SODAオンライン再定義サブプログラムの要約

この表は、SODAオンライン再定義サブプログラムをアルファベット順に示し、簡単に説明しています。

表153-5 SODAオンライン再定義サブプログラム

サブプログラム	用途
ABORT_REDEF_COLLECTIONプロシージャ	このプロシージャは、`CREATE_INTERIM_COLLECTION`、`START_REDEF_COLLECTION`、`COPY_COLLECTION_DEPENDENTS`、`SYNC_INTERIM_COLLETION`またはその他の理由でエラーが発生した場合に、コレクションに加えられた変更を元に戻します。
CAN_REDEF_COLLECTIONプロシージャ	このプロシージャは、データ表を再定義できるかどうかをチェックします。データ表を再定義できない場合は、エラーが発生します。
COPY_COLLECTION_DEPENDENTSプロシージャ	このプロシージャは、元の表に定義されているすべての依存を仮表にコピーします。ただし、仮表がJSON型の場合、`IS JSON NOT NULL`などの制約は無関係であるためコピーされません。
CREATE_INTERIM_COLLECTIONプロシージャ	このプロシージャは、仮の`SODA`コレクションを作成します。interim_metadataは、ユーザーが行う必要がある変更を指定します。たとえば、元のメタデータへのパッチとして適用されるデルタです。
FINISH_REDEF_COLLECTIONプロシージャ	このプロシージャは、1つのアトミック・トランザクションで次のタスクを実行します。それにより、停止時間が発生します。これは、`SODA`データ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。
START_REDEF_COLLECTIONプロシージャ	このプロシージャは、再定義プロセスを開始します。元の表から仮表に既存のデータをコピーし、再定義された列に対して必要な変換を実行します。
SYNC_INTERIM_COLLETIONプロシージャ	このプロシージャは、元のデータ表が変更された場合に、変更内容を仮表に同期します。このプロシージャは、`SODA`データ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。

153.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);

パラメータ

表153-6 ABORT_REDEF_COLLECTIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。

153.3.2 CAN_REDEF_COLLECTIONプロシージャ

このプロシージャは、データ表を再定義できるかどうかをチェックします。データ表を再定義できない場合は、エラーが発生します。

構文

DBMS_SODA.CAN_REDEF_COLLECTION (
   collection_name   IN  NVARCHAR2);

パラメータ

表153-7 CAN_REDEF_COLLECTIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。

153.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);

パラメータ

表153-8 COPY_COLLECTION_DEPENDENTSプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。
`ignore_error`	処理で発生したエラーを無視して続行します。
`num_errors`	処理中に発生したエラー数。

153.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);

パラメータ

表153-9 CREATE_INTERIM_COLLECTIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。
`interim_metadata`	再定義する必要のある列およびその再定義方法を指定するパッチ。

使用上のノート

使用できるデルタは次のとおりです。他のフィールドが存在し、それらのフィールドが元のコレクションのメタデータのフィールドと同じではない場合は、エラーが発生すします。

$.contentColumn.sqlType = JSONを設定してCONTENT列をJSON型で再定義すると、必要に応じて、VERSION列が自動的に生成されます。
$.versionColumn.method = UUIDを設定して、UUIDを使用するようにVERSION列を再定義します。
$.tableNameを設定して、この仮のコレクションのデータ表の名前を指定します。このフィールドがない場合は、他のSODAコレクションと同様に、デフォルトのデータ表名が生成されます。ただし、表がすでに存在する場合、コレクションはMAPモードを使用して作成されます。このシナリオでは、マップされる表に制約が定義されていないことを確認します。
ユーザーはデルタを結合することもできます。たとえば、最も一般的なユースケースは、コンテンツ列をJSON型に再定義し、バージョン列をUUIDに再定義することです。これは、Metadata = {"contentColumn" : {"sqlType": "JSON"}, "versionColumn" : {"method": "UUID"}}を使用して行うことができます。

153.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);

パラメータ

表153-10 FINISH_REDEF_COLLECTIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。
`dml_lock_timeout`	待機時間(秒)。この待機時間内にロックが取得されない場合は、エラーが発生します。

使用上のノート

このアクションは元に戻すことができません。このプロシージャの実行後、DBMS_REDEFINITIONパッケージで提供されるROLLBACKプロシージャを実行することはできません。

153.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);

パラメータ

表153-11 START_REDEF_COLLECTIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。
`copy_vpd_opt`	`DBMS_REDEFINITION.CONS_VPD_MANUAL`または`DBMS_REDEFINITION.CONS_VPD_NONE`を指定できます。 `DBMS_REDEFINITION.CONS_VPD_MANUAL`は、VPDポリシーを手動でコピーすることを示すために使用します。`DBMS_REDEFINITION.CONS_VPD_NONE`は、元の表にVPDポリシーがないことを示すために使用します。`NULL`の場合は、`DBMS_REDEFINITION.CONS_VPD_NONE`が使用されます。
`refresh_dep_mviews`	`N`または`Y`を指定できます。`N`に設定すると、`START_REDEF_TABLE`プロシージャの実行時、`SYNC_INTERIM_TABLE`プロシージャの実行のたび、および`FINISH_REDEF_TABLE`プロシージャの実行時に、依存マテリアライズド・ビューの高速リフレッシュが実行されます。`NULL`の場合は、`N`が使用されます。

153.3.7 SYNC_INTERIM_COLLETIONプロシージャ

このプロシージャは、元のデータ表が変更された場合に、変更内容を仮表に同期します。このプロシージャは、SODAデータ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。

構文

DBMS_SODA.SYNC_INTERIM_COLLETION (
   collection_name         IN  NVARCHAR,
   interim_collection_name IN  NVARCHAR2);

パラメータ

表153-12 SYNC_INTERIM_COLLETIONプロシージャのパラメータ

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`interim_collection_name`	仮のコレクションに使用する名前。