A SODAコレクションの再定義

オンライン再定義を使用して、既存のコレクションのメタデータまたはその他のプロパティを変更できます。特に、アップグレード後にデータベース初期化パラメータのcompatibleを20以上にすると、新しいデフォルト・メタデータを反映するようにコレクションを移行できます。

compatible初期化パラメータが20以上のデータベースのデフォルトのコレクション・メタデータのメタデータ・フィールドcontentColumn.sqlTypeの値は、"JSON"です。また、メタデータ・フィールドversionColumn.methodの値は"UUID"です。compatible設定が20以上の場合、Oracleでは、これらの値を使用するように、オンライン再定義を使用して既存のコレクションのメタデータを変更することをお薦めします。

SODAコレクションのオンライン再定義は、データベース表のオンライン再定義に似ています。コレクションに使用されるPL/SQLプロシージャ(パッケージDBMS_SODA内)は、パッケージDMBS_REDEFINITIONの表の対応するプロシージャに似ています。

コレクションを再定義するには、SODAオンライン再定義プロシージャを1つずつ適用します。各ステップで、エラーが発生した場合に、サブプログラムDBMS_SODA.abort_redef_collectionを使用して移行プロセスを中止できます。

たとえば、ここに示すステップでは、初期化パラメータcompatibleが20以上のデータベースのデフォルト・メタデータが反映されるように、コレクションMyCollectionを移行します。

次のコードは、BLOBコンテンツとして格納されたテキストのJSONデータを使用する、移行対象の初期コレクションを作成します。20未満のパラメータcompatibleを持つデータベースのデフォルト・メタデータは、説明のために明示的に指定します。特に、contentColumn.sqlTypeは"BLOB"で、versionColumn.methodは"SHA256"です。

v_original_collection := 'MyCollection';
v_original_metadata :=
  '{"keyColumn": {"name": "ID",
                  "sqlType": "VARCHAR2",
                  "maxLength": 255,
                  "assignmentMethod": "UUID"},
    "contentColumn": {"name": "JSON_DOCUMENT",
                      "sqlType": "BLOB",
                      "compress": "NONE",
                      "cache": true,
                      "encrypt": "NONE",
                      "validation": "STANDARD"},
    "versionColumn": {"name": "VERSION",
                      "method": "SHA256"},
    "lastModifiedColumn": {"name": "LAST_MODIFIED"},
    "creationTimeColumn": {"name": "CREATED_ON"},
    "readOnly": false}';

DBMS_SODA.create_collection(v_original_collection,
                            v_original_metadata);

次のステップでは、フィールドcontentColumn.sqlTypeおよびversionColumn.methodを変更します。適用されなくなったフィールド(compress、cache、encryptおよびvalidation)が削除されたことを除き、その他のメタデータ・フィールドは変更されません。(これらのフィールドは、JSONデータ型として格納されているドキュメント・コンテンツには適用されません。)

コレクションのオンライン再定義を実行するには、次のデータベース権限が必要です。

• PL/SQLパッケージDBMS_REDEFINITIONの権限EXECUTE

• システム権限CREATE MATERIALIZED VIEW

• システム権限CREATE TABLE、またはコレクションが現在のものとは異なるデータベース・スキーマの表によってバックアップされている場合、CREATE ANY TABLE

関連項目:

『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』のSODAオンライン再定義サブプログラムのサマリーに関する項を参照してください

1. サブプログラムcan_redef_collectionを使用して、コレクションがオンライン再定義に適格かどうかをチェックします。適格でない場合、エラーが発生します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollection';
     DBMS_SODA.can_redef_collection(v_original_collection);
   END;

2. サブプログラムcreate_interim_collectionを使用して、元のコレクションがSODA操作の本番ワークロードの処理を続行する間に、データのコピー先となる暫定コレクションを作成します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollection';
     v_interim_collection := 'MyCollection_int';
     v_metadata := '{"contentColumn": {"sqlType": "JSON"},
                     "versionColumn": {"method": "UUID"}}}';
   
     DBMS_SODA.create_interim_collection(v_original_collection,
                                         v_interim_collection,
                                         v_metadata);
   END;

   引数v_metadataは、変更するメタデータを指定します。変更されないメタデータを指定する必要はありません。

   暫定コレクションのメタデータ(引数v_metadata)には、暫定コレクションがマップされる表の名前を指定するために、元のコレクションとは異なるtableName値を含めることができます。

   この表がすでに存在する場合、マップされた暫定コレクションがその上に作成されます。この場合、表に依存(索引、制約またはトリガー)を持たないようにする必要があります。そうしないと、エラーが発生します。このような依存は、ステップ4で元のコレクションから取得(コピー)されます

3. サブプログラムstart_redef_collectionを使用して、コレクションの再定義のプロセスを開始します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollection';
     v_interim_collection := 'MyCollection_int';
   
     DBMS_SODA.start_redef_collection(v_original_collection,
                                      v_interim_collection);
   END;

   元のコレクションに仮想プライベート・データベース(VPD)ポリシーがある場合は、start_redef_collectionを使用する前にそれらのポリシーを暫定コレクションにコピーします。その場合は、VPDポリシーが手動でコピーされたことを示すために、start_redef_collection(v_original_collection, v_interim_collection, DBMS_REDEFINITION.cons_vpd_manual)を使用します。
4. サブプログラムcopy_collection_dependentsを使用して、元のコレクションに依存するすべてを暫定コレクションにコピーします。これには、すべての制約および索引(SODAによって自動的に定義された索引を含む)が含まれます。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
     v_metadata                 VARCHAR2(2000);
     v_num_errors               NUMBER;
   BEGIN
     v_original_collection := 'MyCollection';
     v_interim_collection := 'MyCollection_int';
   
     DBMS_SODA.copy_collection_dependents(v_original_collection,
                                          v_interim_collection,
                                          num_errors => v_num_errors);
   END;

   出力パラメータnum_errorsの値v_num_errorsは、発生したエラーの数を示します。

   変更するコレクションにJSONコンテンツの索引などのユーザー定義の依存がない場合でも、内部SODA定義の依存が常にいくつか存在し、暫定コレクションにコピーする必要があります。

5. サブプログラムsync_interim_collectionを使用して、暫定コレクションのデータを元のコレクションのデータと同期し、最後のステップでの停止時間を最小限に抑えます(ステップ7)。これは、暫定コレクションでオンライン再定義を実行しているときに、元のコレクションで多くのDML操作を実行する場合に実行します。

   サブプログラムsync_interim_collectionは、SODAコレクションに必要なすべての依存をチェックします。1つでも存在すると、エラーが発生します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollection';
     v_interim_collection := 'MyCollection_int';
   
     DBMS_SODA.sync_interim_collection(v_original_collection,
                                       v_interim_collection);
   END;

6. オプション:

   警告:

   このステップは重要です。ステップ 7の結果は元に戻せません。

   暫定コレクションが期待どおりに機能することを確認します。機能しない場合は、次のように、サブプログラムDBMS_SODA.abort_redef_collectionを使用して変更を元に戻します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollectionName';
     v_interim_collection := 'MyCollectionName_int';
   
     DBMS_SODA.abort_redef_collection(v_original_collection,
                                      v_interim_collection);
   END;

7. サブプログラムfinish_redef_tableを使用して、再定義プロセスを終了します。元のコレクションと暫定コレクションの名前を入れ替えます。

   このステップの結果は元に戻せません(コミットされず、エラーが発生していない場合)。

   finish_redef_tableの実行中は、両方のコレクションがロックされます。暫定コレクションは、このステップ中に元のコレクションと同期されます。これには、sync_interim_collectionの最終使用以降(またはsync_interim_collectionを使用していない場合はstart_redef_collection以降)に元のコレクションで行われたDMLの実行が含まれます。

   サブプログラムは、SODAコレクションに必要なすべての依存をチェックします。1つでも存在すると、エラーが発生します。

   DECLARE
     v_original_collection_name NVARCHAR2(2000);
     v_interim_collection_name  NVARCHAR2(2000);
   BEGIN
     v_original_collection := 'MyCollection';
     v_interim_collection := 'MyCollection_int';
   
     DBMS_SODA.finish_redef_collection(v_original_collection, 
                                       v_interim_collection;
   END;