DBMS_JSON

89 DBMS_JSON

DBMS_JSONパッケージは、データ・ガイド操作のためのインタフェースを提供します。

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

89.1 DBMS_JSONの概要

DBMS_JSONパッケージは、Oracle Databaseに格納されているJavaScript Object Notation (JSON)データを操作するためのサブプログラムを提供します。

89.2 DBMS_JSONのセキュリティ・モデル

PUBLICには、DBMS_JSONパッケージに対するEXECUTE権限が付与されます。サブプログラムは、実行者権限で実行されます。

89.3 DBMS_JSONの定数

DBMS_JSONパッケージは、これらの定数を使用してJSONスキーマ・タイプおよびデータ・ガイドのフォーマット・オプションを定義します。

表89-1 JSONデータ・ガイド・フォーマットに定義されているDBMS_JSON定数

名前	値	説明
FORMAT_FLAT	2	フラット・フォーマットを表示します。
FORMAT_HIERARCHICAL	1	階層フォーマットを表示します。
PRETTY	1	読みやすくするために、適切なインデントを使用します。

表89-2 JSONスキーマ・タイプのDBMS_JSON定数

名前	タイプ	値	説明
TYPE_ARRAY	NUMBER(2)	6	JSON配列
TYPE_BOOLEAN	NUMBER(2)	2	JSONブール
TYPE_OBJECT	NUMBER(2)	5	JSONオブジェクト
TYPE_NULL	NUMBER(2)	1	JSON NULL値
TYPE_NUMBER	NUMBER(2)	3	JSON数値
TYPE_STRING	NUMBER(2)	4	JSON文字列

89.4 DBMS_JSONサブプログラムの要約

この表は、DBMS_JSONサブプログラムを示し、簡単に説明しています。

DBMS_JSONパッケージのサブプログラム

サブプログラム	説明
ADD_VIRTUAL_COLUMNSプロシージャ	データ・ガイド情報に基づいて仮想列を追加します。シャード・カタログ・サーバー上で実行した場合、効果はありません。仮想列は追加されません。
CREATE_VIEWプロシージャ	データ・ガイドでの指定に従い、リレーショナル列およびスカラーJSONフィールドを含むビューを作成します。
CREATE_VIEW_ON_PATHプロシージャ	データ・ガイドの情報に基づき、リレーショナル列、トップ・レベルのスカラー・タイプおよび指定されたパスの下で完全に展開されたサブツリーを使用してビューを作成します。シャード・カタログ・サーバー上で実行された場合は、データ・ガイドが空であることを示すエラーが表示されます。
DROP_VIRTUAL_COLUMNSプロシージャ	`add_virtual_columns`プロシージャにより作成された仮想列を削除します。シャード・カタログ・サーバー上で実行した場合、効果はありません。
GET_INDEX_DATAGUIDEファンクション	データ・ガイドが有効なJSON検索索引からJSONデータ・ガイドを取得します。シャード・カタログ・サーバー上で実行された場合は、単一の空の行が結果として戻されます。
RENAME_COLUMNプロシージャ	データ・ガイドを使用して作成されるビュー列または仮想列に適切な名前を設定します。シャード・カタログ・サーバー上で実行した場合、効果はありません。

ノート:

シャーディングのコンテキスト内では、各シャードがそのシャードに格納されているJSONドキュメントから取得する、独自のデータ・ガイド情報を保持しています。データ・ガイド情報を使用するこのパッケージのプロシージャは、個別のシャードで実行された場合、そのシャードで保持されている情報のみを使用します。

89.4.1 ADD_VIRTUAL_COLUMNSプロシージャ

このプロシージャは、データ・ガイドに基づいて仮想列を追加します。

仮想列の名前は、データ・ガイドのo:preferred_vc_nameの値です。プロシージャは、データ・ガイドのJSONオブジェクト、配列および配列下のフィールドを無視します。仮想列が追加される前に、まずプロシージャadd_virtual_columnsは、以前のadd_virtual_columnsの起動、またはデータ・ガイド変更トリガー・プロシージャadd_vc (実質的に、このプロシージャの実行内容はプロシージャDBMS_JSON.drop_virtual_columnsと同じ)によって同じJSON列内のフィールドから投影された既存の仮想列を削除します。

参照:

構文

DBMS_JSON.ADD_VIRTUAL_COLUMNS (
    tablename  IN  VARCHAR2, 	                
    jcolname   IN  VARCHAR2, 	                
    dataguide  IN  CLOB);

次の署名では、JSON列にデータ・ガイドが有効な検索索引が含まれている必要があります。(これは、前述の署名では必要ありません。)

DBMS_JSON.ADD_VIRTUAL_COLUMNS (
    tablename  IN  VARCHAR2, 	                
    jcolname   IN  VARCHAR2, 	
    frequency      NUMBER    DEFAULT 0,                
    hidden         BOOLEAN   DEFAULT FALSE);

パラメータ

表89-3 ADD_VIRTUAL_COLUMNSプロシージャのパラメータ

パラメータ	説明
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	仮想列を作成する基となるデータを含む`tablename`表のJSON列の名前。
`frequency`	JSON列を表示するための最小頻度しきい値を設定します。頻度が0の場合、すべてのJSON列が表示されます。また、統計が収集されていない場合もすべてのJSON列が表示され、このパラメータによって設定された値が上書きされます。
`hidden`	`TRUE`は追加された仮想列が非表示になることを意味し、`FALSE`は非表示にならないことを意味します。デフォルトは`FALSE`です。
`dataguide`	データ・ガイド。データ・ガイドの特定のJSONフィールドで`o:hidden`が`TRUE`に設定されている場合、対応する仮想列が非表示列として追加されます。`o:hidden`のデフォルト値は`FALSE`です。

使用上のノート

DBMS_STATS.GATHER_STATSプロシージャは、データ・ガイドで統計を収集します。頻度統計が収集されていない場合、頻度はNULLです。頻度をゼロより大きい値に設定すると、頻度統計が収集されていない(統計がNULLの)列は含められません。ただし、DBMS_STATS.GATHER_STATSが実行されていない場合を除きます。その場合、頻度パラメータは無視され、すべての列がビューに表示されます。

89.4.2 CREATE_VIEWプロシージャ

このプロシージャは、データ・ガイドでの指定に従い、スカラーJSONフィールドを使用してリレーショナル列を含むビューを作成します。このプロシージャには、データ・ガイドが有効なJSON検索索引は必要ありません。データ・ガイドはプロシージャに渡されます。

参照:

Oracle Database JSON開発者ガイド

構文

(オプション) ここに構文の情報を入力します。

PROCEDURE CREATE_VIEW (
   viewname VARCHAR2,                       
   tablename VARCHAR2,                       
   jcolname VARCHAR2,                       
   dataguide CLOB);

パラメータ

表89-4 DBMS_JSON.CREATE_VIEWプロシージャのパラメータ

パラメータ	説明
`viewname`	ビューの名前。
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	ビューを作成するために使用される、`tablename`表のJSON列の名前。
`dataguide`	データ・ガイド。

89.4.3 CREATE_VIEW_ON_PATHプロシージャ

このプロシージャは、トップ・レベルのスカラー値および指定されたパスの下で展開されたサブツリーのスカラー値を使用して、リレーショナル列を含むビューを作成します。JSON列には、データ・ガイドが有効な検索索引が含まれている必要があります。

参照:

Oracle Database JSON開発者ガイド

構文

PROCEDURE CREATE_VIEW_ON_PATH(
   viewname VARCHAR2, 
   tablename VARCHAR2, 
   jcolname VARCHAR2, 
   path VARCHAR2,
   frequency NUMBER DEFAULT 0);

パラメータ

表89-5 CREATE_VIEW_ON_PATHプロシージャのパラメータ

パラメータ	説明
`viewname`	ビューの名前。
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	ビューを作成するために使用される、`tablename`表のJSON列の名前。この列には、データ・ガイドが有効なJSON検索索引が含まれている必要があり、そうでない場合はエラーが発生します。
`path`	展開するJSONフィールドのパス。JSONパス式構文が使用されます。これは、指定されたパスの下にある子を展開し、表示されたサブツリー内のスカラー値ごとにビュー列を作成します。パス`$`を指定すると、JSONドキュメント・ルートから始まるビューが作成されます。
`frequency`	JSON列を表示するための最小頻度しきい値。頻度が0の場合、すべてのJSON列が表示されます。統計が収集されていない場合もすべてのJSON列が表示され、このパラメータによって設定された値が上書きされます。ビューには、`frequency`で指定された値より高い頻度を持つJSONフィールドのみが表示されます。指定された頻度が0より大きい場合、統計の収集後に追加されたJSONフィールドのうち、統計列が`NULL`であるフィールドは表示されません。

89.4.4 DROP_VIRTUAL_COLUMNSプロシージャ

PL/SQLプロシージャDBMS_JSON.add_virtual_columnsまたはデータ・ガイド変更トリガー・プロシージャadd_vcを使用して追加された仮想列をすべて削除します。

参照:

構文

PROCEDURE DROP_VIRTUAL_COLUMNS(
   tablename VARCHAR2,                                
   jcolname VARCHAR2);

パラメータ

表89-6 DBMS_JSON.DROP_VIRTUAL_COLUMNSプロシージャのパラメータ

パラメータ	説明
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	`tablename`表のJSON列の名前。

89.4.5 GET_INDEX_DATAGUIDEファンクション

GET_INDEX_DATAGUIDEは、データ・ガイドが有効なJSON検索索引からJSONデータ・ガイドを取得します。

参照:

Oracle Database JSON開発者ガイド

構文

FUNCTION GET_INDEX_DATAGUIDE(
   tablename VARCHAR2,
   jcolname VARCHAR2,
   format NUMBER,
   pretty NUMBER DEFAULT 0) 
   RETURN CLOB;

パラメータ

表89-7 DBMS_JSON.GET_INDEX_DATAGUIDEプロシージャのパラメータ

パラメータ	説明
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	データ・ガイドが有効なJSON検索索引を持つ、`tablename`表のJSON列の名前。
`format`	データ・ガイド・フォーマットは次のとおりです。 `FORMAT_HIERARCHICAL` - 階層フォーマット `FORMAT_FLAT` - フラット・フォーマット
`pretty`	`DBMS_JSON.PRETTY`の値を指定すると、読みやすくするためにインデントを使用し、整形されたデータ・ガイドが出力されます。

例89-1 整形された階層フォーマットでデータ・ガイドを出力する例

この例では、階層フォーマットでデータ・ガイドが戻されます。

SELECT DBMS_JSON.GET_INDEX_DATAGUIDE(‘T1’, ‘PO’, DBMS_JSON.FORMAT_HIERARCHICAL, DBMS_JSON.PRETTY) 
FROM DUAL;

89.4.6 RENAME_COLUMNプロシージャ

このプロシージャは、ビューの作成または仮想列の追加プロシージャにより使用されるJSON列に適切な名前を設定します。

参照:

Oracle Database JSON開発者ガイド

構文

PROCEDURE RENAME_COLUMN(
   tablename VARCHAR2,
   jcolname VARCHAR2,
   path VARCHAR2,
   type NUMBER,
   preferred_name VARCHAR2);

パラメータ

表89-8 RENAME_COLUMNプロシージャのパラメータ

パラメータ	説明
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	`tablename`表のJSON列の名前。データ・ガイドが有効なJSON検索索引が含まれている必要があり、そうでない場合はエラーが発生します。
`path`	適切な列名を設定するJSONフィールドのパス。
`type`	`path`の対象であるJSONフィールドのタイプ。タイプが異なっていれば、2つのJSONフィールドに同じパスを指定できます。有効な値は、次のとおりです。 `TYPE_NULL` `TYPE_STRING` `TYPE_NUMBER` `TYPE_BOOLEAN` `TYPE_OBJECT` `TYPE_ARRAY`
`preferred_name`	`path`により指定されるJSONフィールドの適切な名前。名前の競合がある場合は、かわりにシステム生成の名前が使用されます。

例89-2 列の名前変更の例

この例では、フィールドの名前をitem_nameに変更します。

EXEC DBMS_JSON.RENAME_COLUMN(‘T1’, ‘PO’, ‘$.purchaseOrder.items.name’, DBMS_JSON.TYPE_STRING, ‘item_name’);