JSONデータ・ガイドのフィールド

データ・ガイド内のフィールドの出現箇所は、JSON文書セットのいずれか、または複数の中に存在する1つのフィールドに対応します。

JSONスキーマ・データ・ガイドのフィールド(キーワード)

JSONスキーマはJSONオブジェクトが格納されたJSON文書であり、それ自体に子オブジェクト(サブスキーマ)を含めることができます。JSONスキーマで定義されているフィールドは、JSONスキーマ・キーワードと呼ばれます。表24-2に、Oracle JSONデータ・ガイドで使用できるキーワードを示します。キーワードproperties、itemsおよびoneOfは、階層データ・ガイドおよびスキーマ・データ・ガイド(どちらもJSONスキーマ)でのみ使用されます。キーワードtypeは、3種類のデータ・ガイドすべてで使用されます。

表24-2 JSONスキーマ・データ・ガイドのフィールド(キーワード)

フィールド(キーワード)	値の説明
`properties`	メンバーが階層またはスキーマ・データ・ガイドによって表されるJSONデータで使用されるJSONオブジェクトのプロパティを表すオブジェクト。
`items`	メンバーが階層またはスキーマ・データ・ガイドによって表されるJSONデータで使用される配列の要素(項目)を表すオブジェクト。
`oneOf`	個々の項目が階層またはスキーマ・データ・ガイドによって表されるJSONデータでのJSONフィールドの1つ以上の出現箇所を表す配列。
`type`	データ・ガイド(任意の種類)によって表される一部のJSONデータの型を指定する文字列。使用可能な値は、`array`、`"boolean"`、`"GeoJSON"`、`"null"`、`"number"`、`"object"`、`"string"`で、また`JSON`型データの場合は、`"binary"`、`"date"`、`"daysecondInterval"`、`"double"`、`"float"`、`"timestamp"`、`timestamp with time zone`および`"yearmonthInterval"`です。オプション`DBMS_JSON.DETECT_DATETIME`がファンクション`json_dataguide`へのフラグ・パラメータとして渡された場合、OracleでサポートされているISO日付/時間書式に準拠するデータ内の文字列フィールド値は、`type`が`"string"`ではなく`"timestamp"`または`timestamp with time zone`であるとして記録されます。

Oracle固有のデータ・ガイド・フィールド

JSONスキーマ・キーワードに加えて、JSONデータ・ガイドはOracleデータ・ガイド固有のフィールドを格納できます。すべてのフィールド名に、接頭辞o:が付きます。これについては、表24-3で説明します。

表24-3 Oracle固有のデータ・ガイドのフィールド

フィールド	値の説明
`o:path`	JSON文書からJSONフィールドへのパスを示します。フラット・データ・ガイドでのみ使用されます。値は単純なSQL/JSONパス式(フィルタ式なし)であり、緩和(暗黙的配列ラッピングまたはラッピングなし)およびワイルドカード配列ステップが付くことがあります。これには配列索引または範囲指定含む配列ステップはありません。また、関数ステップもありません。SQL/JSONパス式の構文を参照してください。
`o:length`	JSONフィールド値の最大長をバイト単位で示します。値は常に2の累乗です。たとえば、すべての実際のフィールド値の最大長が5である場合、`o:length`の値は8です(5以上の2の最小のべき乗数)。
`o:preferred_column_name`	所定のデータ・ガイドに固有の識別子であり、大文字と小文字が区別されます。ビュー列またはデータ・ガイドを使用して作成された仮想列に使用する名前として選択します。形式パラメータ`DBMS_JSON.FORMAT_FLAT`を指定するか、形式パラメータを指定しない(`DBMS_JSON.FORMAT_FLAT`がデフォルト)でSQLファンクション`json_dataguide`を使用してデータ・ガイドが取得された場合、このフィールドは存在しません。
`o:frequency`	所定のフィールドを含むJSON文書の割合を示します。同じ配列の下に発生したフィールドの重複は無視されます。(統計情報が文書セットに関して収集された場合にのみ、使用できます。) データ・ガイドがSQLファンクション`json_dataguide`を使用して取得された場合、3番目のパラメータで`DBMS_JSON.gather_stats`が指定されていないかぎり、このフィールドは存在しません。データ・ガイドがPL/SQLファンクション`get_index_dataguide`を使用して作成された場合は、文書セット内のすべての文書が考慮されます。それ以外の場合は、`json_dataguide`問合せの対象となる文書のみが考慮されます。
`o:num_nulls`	対象のスカラー・フィールドの値がJSON `null`である文書数を示します。(統計情報が文書セットに関して収集された場合にのみ、使用できます。) データ・ガイドがSQLファンクション`json_dataguide`を使用して取得された場合、3番目のパラメータで`DBMS_JSON.gather_stats`が指定されていないかぎり、このフィールドは存在しません。データ・ガイドがPL/SQLファンクション`get_index_dataguide`を使用して作成された場合は、文書セット内のすべての文書が考慮されます。それ以外の場合は、`json_dataguide`問合せの対象となる文書のみが考慮されます。
`o:high_value`	検査されたすべての文書中での対象のスカラー・フィールドの最高値を示します。(統計情報が文書セットに関して収集された場合にのみ、使用できます。) データ・ガイドがSQLファンクション`json_dataguide`を使用して取得された場合、3番目のパラメータで`DBMS_JSON.gather_stats`が指定されていないかぎり、このフィールドは存在しません。データ・ガイドがPL/SQLファンクション`get_index_dataguide`を使用して作成された場合は、文書セット内のすべての文書が考慮されます。それ以外の場合は、`json_dataguide`問合せの対象となる文書のみが考慮されます。
`o:low_value`	検査されたすべての文書中での対象のスカラー・フィールドの最低値を示します。(統計情報が文書セットに関して収集された場合にのみ、使用できます。) データ・ガイドがSQLファンクション`json_dataguide`を使用して取得された場合、3番目のパラメータで`DBMS_JSON.gather_stats`が指定されていないかぎり、このフィールドは存在しません。データ・ガイドがPL/SQLファンクション`get_index_dataguide`を使用して作成された場合は、文書セット内のすべての文書が考慮されます。それ以外の場合は、`json_dataguide`問合せの対象となる文書のみが考慮されます。
`o:last_analyzed`	統計情報が最後に文書セットに関して収集された日時を示します。(統計情報が文書セットに関して収集された場合にのみ、使用できます。) データ・ガイドがSQLファンクション`json_dataguide`を使用して取得された場合、3番目のパラメータで`DBMS_JSON.gather_stats`が指定されていないかぎり、このフィールドは存在しません。データ・ガイドがPL/SQLファンクション`get_index_dataguide`を使用して作成された場合は、文書セット内のすべての文書が考慮されます。それ以外の場合は、`json_dataguide`問合せの対象となる文書のみが考慮されます。
`o:sample_size`	`DBMS_JSON.gather_stats`を指定する3番目のパラメータとともにSQLファンクション`json_dataguide`を使用する問合せによって選択されたJSON文書の合計数を示します。問合せで`SAMPLE`句を使用すると、サンプル・サイズをさらに制御できます。データ・ガイドが他の方法で取得された場合、このフィールドは存在しません。

すべてのデータ・ガイド形式について、特定のフィールドが文書セットのすべての文書で同じ型である場合、それはデータ・ガイド内のフィールドについてレポートされるtypeです。

特定のフィールドの値が文書セット全体で異なる型である場合、そのフィールドの型は、次のように各種データ・ガイド形式によって異なる方法でレポートされます。

スキーマ・データ・ガイドでは、特定のフィールドに使用されるそれぞれの型を正確にレポートします。1つのフィールドに複数の型がある場合、そのフィールドはキーワードoneOf (値は、異なるtypeを指定するオブジェクトの配列)を使用してレポートされます。

階層データ・ガイドでは、フィールド型は同様にレポートされますが、フィールドが文書セット全体で異なるスカラー値を持つ場合、単一のスカラーtype "string"がレポートされます。つまり、すべての文書でスカラー値がすべて文字列であるかのようになります。

フラット・データ・ガイドでは、異なるtype値("object"、"array")を持つ別個のオブジェクトを使用して、フィールドの非スカラー型をレポートします。階層データ・ガイドと同様に、フィールドが文書セット全体で異なるスカラー値を持つ場合、単一のスカラーtype "string"がレポートされます。

配列要素の型は、フィールドの型と同様に処理されます。

フラットデータ・ガイドおよび階層データ・ガイドの場合、異なる型のスカラー配列要素は個別にレポートされません。かわりに、すべてのスカラー要素値に対して単一のサブスキーマが記録されます。すべての文書でスカラー要素が同じ型の場合、そのtypeが使用されます。それ以外の場合は、type "string"が使用されます。

フラット・データ・ガイドおよび階層データ・ガイドでは、文書セット全体で、配列にスカラー要素と非スカラー要素の両方がある場合またはオブジェクト要素と配列要素の両方がある場合、非スカラー型とスカラー型の両方がレポートされます。レポートされるスカラー型は、前述の指定どおりです(異なるスカラー要素型はtype "string"としてレポートされます)。

配列要素の場合、o:path値(フラット・データ・ガイドにのみ存在)は配列のo:path値で、その後に、すべての配列要素を示すワイルドカード([*])を含む配列が続きます。

フィールドo:preferred_column_name (存在する場合)のデフォルト値は、データ・ガイドがSQLファンクションjson_dataguide(形式DBMS_JSON.FORMAT_HIERARCHICALを指定)を使用して取得されたか、PL/SQLファンクションDBMS_JSON.get_index_dataguideを使用して取得されたかによって異なります。

get_index_dataguide — 対応するJSONフィールド名と同じです。JSON列名が先頭に付き、その後に$が続きます。非ASCII文字は削除されます。この結果のフィールド名が、同じデータ・ガイド内にすでにある場合、新しい順序番号が末尾に付加された固有の名前が付けられます。

JSON列名部分は、その列がエスケープされた小文字(たとえば'PO_Column'がpo_columnのかわりに使用されているなど)を使用して定義されていないかぎり大文字です。

たとえば、JSON列dataにあるデータの、フィールドUserのデフォルト値はDATA$Userです。
json_dataguide(階層形式) — 対応するJSONフィールド名と同じです。

ただし、データ・ガイドに基づいてビューまたは仮想列を作成する場合は、DBMS_JSONプロシージャcreate_view、get_view_sqlおよびadd_virtual_columnsに次のパラメータを指定することで、列のネーミングを制御できます。
- colNamePrefix => prefix — o:preferred_column_nameで指定された列名に接頭辞prefixを付けます。
- mixedCaseColumns => FALSE — 列名の大文字と小文字を区別しません。(デフォルトでは大文字と小文字が区別されます。)
- resolveNameConflicts => TRUE (デフォルト) — 名前の競合を解決します: 結果となるフィールド名が同じデータ・ガイドにすでに存在する場合は、それが一意になるように、新しい順序番号を使用して接尾辞を付けます(get_index_dataguideで提供されるのと同じ動作)。

PL/SQLプロシージャDBMS_JSON.rename_columnを使用して、所定のフィールドおよび型に対するo:preferred_column_nameの値を設定できます。データ・ガイド情報がJSON検索索引の一部として永続化されていない場合、このプロシージャの効力はありません。

フィールドo:preferred_column_nameは、JSON列を格納する表内の新しい仮想列の名前を付けるために使用されます。または、表内のその他の列も格納する新しいビュー内の列の名前を付けるために使用されます。どちらの場合も、フィールドo:preferred_column_nameによって指定される名前は、表内の他の列との間で固有である必要があります。さらに、この名前は、文書セット内のすべての型のすべてのJSONフィールド間で固有である必要があります。DBMS_JSON.get_index_dataguideを使用する場合、これらの方法でデフォルトの名前が固有であることが保証されます。

DBMS_JSON.rename_columnを使用して指定する名前によって競合が発生する場合、指定した名前は無視され、そのかわりにシステムが生成した名前が使用されます。

24.4 JSONデータ・ガイドのフィールド