DBMS_JSON

97 DBMS_JSON

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

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

97.1 DBMS_JSONの概要

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

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

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

97.3 DBMS_JSONの定数

DBMS_JSONパッケージは、これらの定数を使用してJSONスキーマ・タイプおよびデータ・ガイドのフォーマット・オプションおよびマテリアライズド・ビュー・オプションを定義します。mvrefreshmodeパラメータのDBMS_JSON定数は、19c以降のAutonomous Databaseにのみ使用できます。

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

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

表97-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文字列

表97-3 mvrefreshmodeパラメータのDBMS_JSON定数

名前	タイプ	値	説明
MV_REFRESH_ON_STATEMENT	NUMBER(2)	`1`	refresh on文でマテリアライズド・ビューを作成します。
MV_REFRESH_ON_COMMIT	NUMBER(2)	`2`	refresh on commitでマテリアライズド・ビューを作成します。
MV_REFRESH_ON_DEMAND	NUMBER(2)	`3`	refresh on demandでマテリアライズド・ビューを作成します。

97.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ドキュメントから取得する、独自のデータ・ガイド情報を保持しています。データ・ガイド情報を使用するこのパッケージのプロシージャは、個別のシャードで実行された場合、そのシャードで保持されている情報のみを使用します。

97.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,
    resolvenameconflicts    IN  BOOLEAN  DEFAULT FALSE,
    colnameprefix           IN VARCHAR2  DEFAULT NULL,
    mixedcasecolumns        IN BOOLEAN   DEFAULT FALSE);

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

ノート:

パラメータresolvenameconflicts、colnameprefixおよびmixedcasecolumnsは、19c以降のAutonomous Databaseにのみ使用できます。

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

パラメータ

表97-4 ADD_VIRTUAL_COLUMNSプロシージャのパラメータ

パラメータ	説明
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	仮想列を作成する基となるデータを含む`tablename`表のJSON列の名前。
`dataguide`	データ・ガイド。データ・ガイドの特定のJSONフィールドで`o:hidden`が`TRUE`に設定されている場合、対応する仮想列が非表示列として追加されます。`o:hidden`のデフォルト値は`FALSE`です。
`resolvenameconflicts`	デフォルトでは、`o:preferred_column_name`間に競合があると、エラーが発生します。このパラメータを`TRUE`に設定することにより、プロシージャは順序番号を付加することで仮想列名の競合を自動的に解決します。デフォルト値は`FALSE`です。ノート: このパラメータは、19cリリース以降のAutonomous Databaseにのみ使用できます。
`colnameprefix`	デフォルトでは、仮想列名はJSONフィールド名と同じです。このパラメータを使用すると、仮想列名に接頭辞を追加できます。ノート: このパラメータは、19cリリース以降のAutonomous Databaseにのみ使用できます。
`mixedcasecolumns`	デフォルトでは、仮想列名は大/小文字を区別します。このパラメータの値を`TRUE`に設定すると、仮想列名は大/小文字を区別しなくなります。ノート: このパラメータは、19cリリース以降のAutonomous Databaseにのみ使用できます。
`frequency`	JSON列を表示するための最小頻度しきい値を設定します。頻度が0の場合、すべてのJSON列が表示されます。また、統計が収集されていない場合もすべてのJSON列が表示され、このパラメータによって設定された値が上書きされます。
`hidden`	`TRUE`は追加された仮想列が非表示になることを意味し、`FALSE`は非表示にならないことを意味します。デフォルトは`FALSE`です。

使用上のノート

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

97.4.2 CREATE_VIEWプロシージャ

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

参照:

Oracle Database JSON開発者ガイド

構文

PROCEDURE CREATE_VIEW (
   viewname                VARCHAR2,                       
   tablename               VARCHAR2,                       
   jcolname                VARCHAR2,                       
   dataguide               CLOB,
   resourcepath            VARCHAR2 DEFAULT NULL,
   materialize             BOOLEAN  DEFAULT FALSE,
   mvrefreshmode           NUMBER   DEFAULT MV_REFRESH_ON_STATEMENT,
   path                    VARCHAR2 DEFAULT '$',
   resolvenameconflicts    BOOLEAN  DEFAULT FALSE,
   colnameprefix           VARCHAR2 DEFAULT NULL,
   mixedcasecolumns        BOOLEAN DEFAULT FALSE);

パラメータ

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

パラメータ	説明
`viewname`	ビューの名前。
`tablename`	JSON列`jcolname`を含む表の名前。
`jcolname`	ビューを作成するために使用される、`tablename`表のJSON列の名前。
`dataguide`	データ・ガイド。
`resourcepath`	このパラメータは、内部使用のためのものです。このパラメータの値は、常に`NULL`です。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。
`materialize`	このパラメータの値はブール値で、ビューがマテリアライズドかどうかを示します。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。
`mvrefreshmode`	マテリアライズがtrueのとき、このパラメータはマテリアライズド・ビューのリフレッシュ・モードを指定します。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。マテリアライズド・ビューのリフレッシュ・モード・オプションの詳細は、DBMS_JSON定数を参照してください。
`path`	展開する`JSON`フィールドのパス。`JSON`パス式の構文を使用します。これは、指定されたパスの下にある子を展開し、表示されたサブツリー内のスカラー値ごとにビュー列を作成します。パス$は、`JSON`ドキュメント・ルートから始まるビューを作成します。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。
`resolvenameconflicts`	デフォルトでは、`o:preferred_column_name`間に競合があると、エラーが発生します。このパラメータを`TRUE`に設定することにより、プロシージャは順序番号を付加することで仮想列名の競合を自動的に解決します。デフォルト値は`FALSE`です。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。
`colnameprefix`	デフォルトでは、ビュー列名は`JSON`フィールド名と同じです。このパラメータを使用すると、ユーザーはビュー列名に付加する接頭辞を指定できます。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。
`mixedcasecolumns`	デフォルトでは、ビュー列名は大/小文字を区別します。このパラメータを使用して、ビュー列名の大/小文字を区別する動作を変更できます。ノート: このパラメータは、19c以降のAutonomous Databaseにのみ使用できます。

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

パラメータ

表97-6 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`であるフィールドは表示されません。

97.4.4 DROP_VIRTUAL_COLUMNSプロシージャ

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

参照:

構文

PROCEDURE DROP_VIRTUAL_COLUMNS(
   tablename VARCHAR2,                                
   jcolname VARCHAR2);

パラメータ

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

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

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

パラメータ

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

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

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

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

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

97.4.6 RENAME_COLUMNプロシージャ

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

参照:

Oracle Database JSON開発者ガイド

構文

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

パラメータ

表97-9 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フィールドの適切な名前。名前の競合がある場合は、かわりにシステム生成の名前が使用されます。

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

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

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