89 DBMS_JSON
DBMS_JSON
パッケージは、データ・ガイド操作のためのインタフェースを提供します。
この章のトピックは、次のとおりです:
89.1 DBMS_JSONの概要
DBMS_JSON
パッケージは、Oracle Databaseに格納されているJavaScript Object Notation (JSON)データを操作するためのサブプログラムを提供します。
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プロシージャ |
シャード・カタログ・サーバー上で実行した場合、効果はありません。 |
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検索索引は必要ありません。データ・ガイドはプロシージャに渡されます。
構文
(オプション) ここに構文の情報を入力します。
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列には、データ・ガイドが有効な検索索引が含まれている必要があります。
構文
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データ・ガイドを取得します。
構文
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 |
データ・ガイド・フォーマットは次のとおりです。
|
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列に適切な名前を設定します。
構文
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フィールドに同じパスを指定できます。有効な値は、次のとおりです。
|
preferred_name |
path により指定されるJSONフィールドの適切な名前。名前の競合がある場合は、かわりにシステム生成の名前が使用されます。
|
例89-2 列の名前変更の例
この例では、フィールドの名前をitem_nameに変更します。
EXEC DBMS_JSON.RENAME_COLUMN(‘T1’, ‘PO’, ‘$.purchaseOrder.items.name’, DBMS_JSON.TYPE_STRING, ‘item_name’);