24.9 データ・ガイド対応検索索引の変更トリガー

JSONデータが変更されると、データ・ガイド対応のJSON検索索引の一部の情報は自動的に更新されます。これが発生するたびに起動がトリガーされるプロシージャを指定できます。自分のPL/SQLプロシージャをこれに定義でき、事前定義済変更トリガー・プロシージャであるadd_vcを使用することもできます。

データ・ガイド対応JSON検索索引内のデータ・ガイド情報は、構造、型、および場合によってJSON文書セットに関する統計情報を記録します。収集時にのみ更新される統計情報を除いて、文書セット内の関連する変更内容は、索引内に格納されるデータ・ガイド情報に自動的に反映されます。

このような索引の更新によって起動が自動的にトリガーされるPL/SQLプロシージャを定義できます。起動は索引の更新時に発生します。プロシージャの実行中に発生したエラーは無視されます。

事前定義済変更トリガー・プロシージャadd_vcを使用して、文書セットからのJSONフィールドを投影する仮想列を自動的に追加する、または必要に応じてこのような既存の列を変更できます。add_vcによって追加された仮想列は、データ・ガイド対応検索索引を持つJSON列用にプロシージャDBMS_JSON.add_virtual_columnsの起動によって追加された列と同じ命名規則に従います。

この場合、プロシージャの実行中に発生したエラーは無視されます。

DBMS_JSON.add_virtual_columnsとは異なり、add_vcは、最初に同じJSON列内のフィールドから投影された既存の仮想列を削除することはありません。add_vcまたはadd_virtual_columnsによって同じJSON列内のフィールドから投影された仮想列を削除するには、プロシージャDBMS_JSON.drop_virtual_columnsを使用します。

データ・ガイドの変更のために、JSON検索索引の作成時または変更時に、キーワードDATAGUIDE ON CHANGEをPARAMETERS句内で使用することによって、トリガーを使用することを指定します。索引ごとに、1つの変更トリガーのみが許可されます。トリガーを指定する索引を変更することで、そのための以前の任意トリガーは自動的に置換されます。

例24-15は、既存のJSON検索索引po_search_idxを変更して、プロシージャadd_vcを使用するようにします。

例24-15 変更トリガーADD_VCによる仮想列の自動的な追加

この例では、事前定義済変更トリガーadd_vcをJSON検索索引po_search_idxに追加します。

まず、プロシージャDBMS_JSON.add_virtual_columnsによって、または同じJSON検索索引の既存のadd_vc変更トリガーによってJSON列data内のフィールドから投影された、既存の仮想列を削除します。

次に、検索索引を変更し、変更トリガーadd_vc (すでに存在する場合、これに効力はありません)を追加します。

最後に、データ・ガイドに変更を発生させる新しい文書を挿入します。2つの仮想列が、配列下にない2つのスカラー・フィールド用に表に追加されます。

EXEC DBMS_JSON.drop_virtual_columns('J_PURCHASEORDER', 'DATA');

ALTER INDEX po_search_idx REBUILD
  PARAMETERS ('DATAGUIDE ON CHANGE add_vc');

INSERT INTO j_purchaseorder
  VALUES (
    SYS_GUID(),
    to_date('30-JUN-2015'),
    '{"PO_Number"     : 4230,
      "PO_Reference"  : "JDEER-20140421",
      "PO_LineItems"  : [ {"Part_Number"  : 230912362345,
                           "Quantity"     : 3.0} ]}');

DESCRIBE j_purchaseorder;
 Name                      Null?    Type
 ------------------------- -------- ----------------------------
 ID                        NOT NULL RAW(16)
 DATE_LOADED                        TIMESTAMP(6) WITH TIME ZONE
 DATA                               CLOB
 DATA$PO_Number                    NUMBER
 DATA$PO_Reference                 VARCHAR2(16)

_________________________________________________________

関連項目:

• Oracle Database PL/SQLパッケージおよびタイプ・リファレンス (DBMS_JSON.add_virtual_columnsに関する詳細)

• Oracle Database PL/SQLパッケージおよびタイプ・リファレンス(DBMS_JSON.drop_virtual_columnsに関する詳細)

• ユーザー定義のデータ・ガイド変更トリガー
  所定のデータ・ガイド対応JSON検索索引が更新されるたびに、自動的に起動がトリガーされるプロシージャを定義できます。プロシージャの実行中に発生したエラーは無視されます。

24.9.1 ユーザー定義のデータ・ガイド変更トリガー

所定のデータ・ガイド対応JSON検索索引が更新されるたびに、自動的に起動がトリガーされるプロシージャを定義できます。プロシージャの実行中に発生したエラーは無視されます。

例24-16に、これを示します。

JSON検索索引のPARAMETERS句内でキーワードDATAGUIDE ON CHANGEとともに指定されたユーザー定義のプロシージャは、表24-5に明記されたパラメータを受け入れる必要があります。

表24-5 ユーザー定義のデータ・ガイド変更トリガー・プロシージャのパラメータ

名前	型	説明
table_name	VARCHAR2	列column_nameを格納する表の名前です。
column_name	VARCHAR2	データ・ガイド対応JSON検索索引を持つJSON列の名前です。
path	VARCHAR2	列column_nameのデータ内の特定のフィールドを対象とするSQL/JSONパス式です。このパスは、プロシージャの起動をトリガーする索引の変更の影響を受けます。たとえば、索引の変更は、このパスの追加、または値の型や型の長さの値の変更に関係があります。
new_type	NUMBER	指定されたパスの新しい型です。
new_type_length	NUMBER	指定されたパスの新しい型の長さです。

例24-16 ユーザー定義の変更トリガーを使用したデータ・ガイド更新のトレース

この例では、まずJSON列data内のフィールドから投影された既存の仮想列を削除します。

次に、PL/SQLプロシージャmy_dataguide_traceを定義します。これは、表名とJSON列を追加された仮想列のパス、型、長さの各フィールドと一緒に出力します。次に、JSON検索索引po_search_idxを変更し、このプロシージャが、索引内のデータ・ガイド情報への更新に対する変更トリガーとして起動されることを指定します。

次に、データ・ガイドに変更を発生させる新しい文書を挿入します。これにより、トレース情報の出力がトリガーされます。

プロシージャに対するTYPE引数は、JSON型のDBMS_JSON定数のうちの1つの数値である必要があることに注意してください。このプロシージャは、引数をテストし、数値のかわりにユーザーにわかりやすい文字列を出力します。

EXEC DBMS_JSON.drop_virtual_columns('J_PURCHASEORDER', 'DATA');

CREATE OR REPLACE PROCEDURE my_dataguide_trace(tableName VARCHAR2,
                                               jcolName  VARCHAR2,
                                               path      VARCHAR2,
                                               type      NUMBER,
                                               tlength   NUMBER)
  IS
    typename VARCHAR2(10);
  BEGIN
    IF    (type = DBMS_JSON.TYPE_NULL)    THEN typename := 'null';
    ELSIF (type = DBMS_JSON.TYPE_BOOLEAN) THEN typename := 'boolean';
    ELSIF (type = DBMS_JSON.TYPE_NUMBER)  THEN typename := 'number';
    ELSIF (type = DBMS_JSON.TYPE_STRING)  THEN typename := 'string';
    ELSIF (type = DBMS_JSON.TYPE_OBJECT)  THEN typename := 'object';
    ELSIF (type = DBMS_JSON.TYPE_ARRAY)   THEN typename := 'array';
    ELSE                                       typename := 'unknown';
    END IF;
    DBMS_OUTPUT.put_line('Updating ' || tableName || '(' || jcolName
                         || '): Path = ' || path || ', Type = ' || type
                         || ', Type Name = ' || typename
                         || ', Type Length = ' || tlength);
  END;
/

ALTER INDEX po_search_idx REBUILD
  PARAMETERS ('DATAGUIDE ON CHANGE my_dataguide_trace');

INSERT INTO j_purchaseorder
  VALUES (
    SYS_GUID(),
    to_date('30-MAR-2016'),
    '{"PO_ID"     : 4230,
      "PO_Ref"  : "JDEER-20140421",
      "PO_Items"  : [ {"Part_No"       : 98981327234,
                      "Item_Quantity" : 13} ]}');

COMMIT;
Updating J_PURCHASEORDER(DATA):
  Path = $.PO_ID, Type = 3, Type Name = number, Type Length = 4
Updating J_PURCHASEORDER(DATA):
  Path = $.PO_Ref, Type = 4, Type Name = string, Type Length = 16
Updating J_PURCHASEORDER(DATA):
  Path = $.PO_Items, Type = 6, Type Name = array, Type Length = 64
Updating J_PURCHASEORDER(DATA):
  Path = $.PO_Items.Part_No, Type = 3, Type Name = number, Type Length = 16
Updating J_PURCHASEORDER(DATA):
  Path = $.PO_Items.Item_Quantity, Type = 3, Type Name = number, Type Length = 2

Commit complete.

関連項目:

• Oracle Database SQL言語リファレンス(PL/SQL定数TYPE_NULL、TYPE_BOOLEAN、TYPE_NUMBER、TYPE_STRING、TYPE_OBJECT、TYPE_ARRAYの詳細)

• Oracle Database PL/SQLパッケージおよびタイプ・リファレンス(DBMS_JSON.drop_virtual_columnsに関する詳細)