DBMS_SODA

170 DBMS_SODA

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

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

参照:

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

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

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

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

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

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

サブプログラム	用途
CREATE_COLLECTIONファンクション	コレクション名およびメタデータを使用してコレクションを作成します。
DROP_COLLECTIONファンクション	ユーザーのスキーマから既存のコレクションを削除します。これにより、コレクション内のすべてのドキュメントも削除されます。
GET_AS_OF_SCNファンクション	このファンクションは、現行データベースのSCN番号を戻します。
GET_AS_OF_TIMESTAMPファンクション	このファンクションは、現在のデータベース・タイムスタンプ値を戻します。
GET_DEFAULT_METADATA_AS_CLOBファンクション	このファンクションは、デフォルトのメタデータを戻します。
GET_DEFAULT_METADATA_AS_VARCHAR2ファンクション	このファンクションは、デフォルトのメタデータを戻します。
LIST_COLLECTION_NAMESファンクション	ユーザーのスキーマ内のコレクション名を`NVARCHAR2`の表としてリストします。
OPEN_COLLECTIONファンクション	既存のコレクションをオープンします。

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

パラメータ

表170-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開発者ガイド

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

パラメータ

表170-3 DROP_COLLECTIONのパラメータ

パラメータ説明

パラメータ	説明
`collection_Name`	コレクションの名前。 `collection_Name`の値は、大/小文字が区別されます。
`purge`	デフォルト値は`FALSE`です。
`drop_Mapped_Table`	デフォルト値は`FALSE`です。

collection_Name

コレクションの名前。

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

purge

デフォルト値はFALSEです。

drop_Mapped_Table

デフォルト値はFALSEです。

戻り値

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

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

例外

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

参照:

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

170.2.3 GET_AS_OF_SCNファンクション

このファンクションは、現行データベースのSCN番号を戻します。

構文

DBMS_SODA.GET_AS_OF_SCN ( )
 RETURN NUMBER;

戻り値

このファンクションは、現行データベースのSCN番号を戻します。

170.2.4 GET_AS_OF_TIMESTAMPファンクション

このファンクションは、現在のデータベース・タイムスタンプ値を戻します。

構文

DBMS_SODA.GET_AS_OF_TIMESTAMP ( )
 RETURN VARCHAR2;

戻り値

このファンクションは、現在のデータベース・タイムスタンプ値を戻します。

170.2.5 GET_DEFAULT_METADATA_AS_CLOBファンクション

このファンクションは、デフォルトのメタデータを戻します。

構文

DBMS_SODA.GET_DEFAULT_METADATA_AS_CLOB ( )
 RETURN CLOB;

戻り値

このファンクションは、CLOBデータ・タイプを使用してデフォルトのメタデータを戻します。

170.2.6 GET_DEFAULT_METADATA_AS_VARCHAR2ファンクション

このファンクションは、デフォルトのメタデータを戻します。

構文

DBMS_SODA.GET_DEFAULT_METADATA_AS_VARCHAR2 ( )
 RETURN VARCHAR2;

戻り値

このファンクションは、VARCHAR2データ・タイプを使用してデフォルトのメタデータを戻します。

170.2.7 LIST_COLLECTION_NAMESファンクション

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

構文

DBMS_SODA.LIST_COLLECTION_NAMES ()
 RETURN SODA_CollName_List_T;

戻り値

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

例外

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

参照:

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

170.2.8 OPEN_COLLECTIONファンクション

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

構文

DBMS_SODA.OPEN_COLLECTION (
     collection_Name      IN NVARCHAR2)
 RETURN SODA_Collection_T;

パラメータ

表170-4 OPEN_COLLECTIONのパラメータ

パラメータ説明

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

collection_Name

コレクションの名前。

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

戻り値

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

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

例外

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

参照:

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

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

表170-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`データ表に必要なすべての依存が仮のコレクションに移入された後にのみコールできます。移入されていない場合は、エラーが発生します。
TO_UUIDファンクション	このファンクションは、データ・ポンプ・インポート中に、コレクション表のバージョン列をUUID値に再マップするために使用します。このファンクションは、データ・ポンプの`REMAP_DATA`機能でのみ使用します。

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

パラメータ

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

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

170.3.2 CAN_REDEF_COLLECTIONプロシージャ

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

構文

DBMS_SODA.CAN_REDEF_COLLECTION (
   collection_name   IN  NVARCHAR2);

パラメータ

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

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

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

パラメータ

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

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

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

パラメータ

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

パラメータ	説明
`collection_name`	再定義するコレクションの名前。
`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”}}に設定して行うことができます。

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

パラメータ

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

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

使用上のノート

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

注意:

FINISH_REDEF_COLLECTIONプロシージャをコールする前に、仮のコレクションを試して、仮のコレクションにアクセスできることと、それが期待どおりに機能することを確認する必要があります。問題が発生した場合は、ABORT_REDEF_COLLECTIONプロシージャを使用してください。

これは、FINISH_REDEF_COLLECTIONをコールする前に行うことが非常に重要です。FINISH_REDEF_COLLECTIONを元に戻すことはできないためです。

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

パラメータ

表170-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`が使用されます。

170.3.7 SYNC_INTERIM_COLLETIONプロシージャ

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

構文

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

パラメータ

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

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

170.3.8 TO_UUIDファンクション

このファンクションは、データ・ポンプ・インポート中に、コレクション表のバージョン列をUUID値に再マップするために使用します。このファンクションは、データ・ポンプのREMAP_DATA機能でのみ使用します。

構文

DBMS_SODA.TO_UUID (
     placeholder      IN   NVARCHAR2)
 RETURN VARCHAR2;

パラメータ

表170-13 TO_UUIDのパラメータ

パラメータ	説明
`placeholder`	このパラメータは、使用されていないため、無視しても問題ありません。これが使用されるのは、データ・ポンプの`REMAP_DATA`ファンクションに構文の制約があるためです。

戻り値

このファンクションは、UUID値として使用できる16進数の文字列を戻します。

参照:

Oracle® Databaseユーティリティ・ガイドのREMAP_DATA。