SODA索引仕様(参考)

6 SODA索引仕様(参考)

索引仕様を使用してJSONドキュメントのデータに索引付けできます。SODA索引仕様の詳細な定義を示します。

注意:

Bツリー索引を作成するには、Oracle Databaseリリース12c (12.2.0.1)以上が必要です。DATEまたはTIMESTAMP値に索引付けするBツリー索引を作成するには、Oracle Databaseリリース18c (18.1)以上が必要です。
空間索引または検索索引を作成するには、Oracle Databaseリリース12c (12.2.0.1)以上が必要です。

索引仕様は、JSONドキュメントに対する操作に使用される特定の種類のデータベース索引を指定するJSONオブジェクトです。次の種類の索引を指定できます。

Bツリー: スカラーJSON値の索引付けに使用されます。フィールドfieldsの有無で識別されます。(Bツリー索引のみが、このフィールドを持っています。)
空間: GeoJSON地理データを索引付けするために使用されます。フィールドspatialの有無で識別されます。(空間索引のみが、このフィールドを持っています。)
検索: 次のいずれか、または両方に使用されます。
- 非定型の構造的問合せまたは全文検索
- JSONデータ・ガイド
検索索引仕様は、フィールドfieldsおよびspatialの欠如によって識別されます。

各種類の索引仕様にnameフィールドが必要です。これは索引の名前を指定する文字列です。

Bツリー索引仕様

SODA Bツリー索引仕様では、JSONドキュメントにスカラー値を問い合せるためにSODAが使用するSQL/JSON関数json_valueに対して、Bツリー関数ベースの索引を指定します。Bツリー索引仕様では、次のフィールドを持つことができます。フィールドfieldsは、Bツリー索引仕様に必要です。その他のフィールドはオプションです。

fields — 索引付けされスカラーJSON値を持つドキュメントのフィールドをターゲットとする、オブジェクトの配列。

配列内の各オブジェクトには、次のフィールドを指定できます。
- path - ターゲット値へのパスを指定する文字列。その値はスカラーであることが必要です。必須です。
  
  パス内に配列ステップがある場合、このような各配列の最初の要素のみが索引付けに使用されます。ドキュメントでは、ターゲット・フィールドのスカラー値のみが索引によって処理され、フィールドの非スカラー値は索引によって無視されます。
- datatype - 索引付けの目的で、targeted-field値のデータ型を指定する文字列。オプションです。可能な値(すべて大/小文字は区別されません):"varchar2"(デフォルト)、"number"、"date" "timestamp"および"varchar2"シノニム"string"と"varchar"。
  
  QBEフィルタ基準と一致する入力データの有効なタイプが索引datatype値と一致する場合、QBEフィルタ基準を評価する際のパフォーマンスを向上させるために、索引を使用できます。
  
  索引を取得して特定のQBEを評価するには、QBEで対象になっているスカラーJSON値を索引仕様のdatatype値と同じSQLデータ型として解釈することで十分です。これは、JSONの数値または文字列値および索引で、datatypeがそれぞれ"number"または"varchar2"(または"varchar2"シノニム、またはdatatypeなし)の場合です。
  
  他のdatatype値の場合には、直接対応するJSONスカラー・データ型がないため、QBEで索引を取得するには、項目メソッド演算子を使用してJSON値を適切なデータ型のSQL値に変換する必要があります。
  
  たとえば、{"dateField" : {"$date" : "2017-07-25"}}のようなQBEで入力文字列値"2017-07-25"(サポートされているISO 8601日付書式の1つ)は、QBEの項目メソッド演算子$dateによってデータ型"date"に変換されます。"date"のdatatype値で指定された索引を取得して、QBEを評価できます。
  
  項目メソッド演算子$numberまたは$stringを明示的に使用しないQBEでは、datatypeがそれぞれ"number"または"varchar2" (またはそのシノニムの1つ)である索引を取得できます。このような値ではJSONとSQLデータ型の間に直接的な対応があるためです。次に例を示します。
  - {"numField" : {"$number" : 20}}を使用するのと同じように、QBE {"numField" : 20}を使用すると、datatype値"number"で作成された索引を取得できます。
  - {"stringField" : {"$string" : "my string"}}を使用するのと同じように、QBE {"stringField" : "my string"}を使用すると、datatype値"varchar2" (またはそのシノニムの1つ)で作成された索引を取得できます。
- maxlength — 索引付けする値の最大長を指定する数値。オプションです。datatype が長さを持たないもの(numberなど)の場合は無視されます。maxlengthが指定されていない場合、索引付けされた値の長さは、索引付けされているstringフィールドの数で4000を割ったものです。
- order — varchar2 (またはそのシノニムの1つ)、またはnumberのdatatypeに対して、ソート順序を索引付けします。オプションです。フィールドorderの値は、昇順を意味する文字列"asc"または数値1、あるいは降順を意味する文字列"desc"または数値-1が可能です。デフォルト: 昇順。
  
  索引ソート順は、複数の関連フィールドを索引付けする(つまり、結果がコンポジットBツリー索引になる)仕様に特に関係します。配列フィールドの要素の順序は、プライマリ索引付け順序、つまりターゲット・フィールド間の順序(最初の配列要素のフィールドが最優先される)を指定します。orderの値は、1つのターゲット・フィールド(pathで指定)の索引ソート順を指定します。
unique — ブール値。オプションです。索引が一意かどうか。デフォルト: 一意でない(false)。
indexNulls — ブール値。オプションです。選択した列に対してNULL値を索引付けするかどうか(索引付けする列のリストに1を加算)。デフォルト: NULL値を索引付けしません(false)。

注意:

QBEのorderby句で索引が取得されるように、indexNullsにはtrue値を指定する必要があります。

デフォルトのエラー処理動作では、ターゲット・フィールドが存在する必要はありませんが、存在する場合、その値はdatatypeデータ型に変換可能なJSONスカラーである必要があります。ドキュメントについて、そうでない場合には問合せ時にエラーが発生します。さらに、このような索引が存在する場合に、そうではないドキュメントを書き込もうとすると、書込み操作のエラーが発生します。^脚注1

Bツリー索引仕様では、フィールドscalarRequiredにtrue値を指定することで、デフォルトとは異なるエラー処理動作を指定できます。これには、ターゲット・フィールドが存在し、データ型datatypeに変換可能な値が必要です。索引付けするドキュメントについて、そうでない場合には索引付け時にエラーが発生します。さらに、このような索引が存在する場合に、そうではないドキュメントを書き込もうとすると、書込み操作のエラーが発生します。^脚注2

注意:

データ内のJSON null値は、常に、索引に指定されたデータ型に変換可能です。そのデータは索引付けされていません。(これは、scalarRequiredの値に関係なく適用されます。)

空間索引仕様

SODA空間索引仕様では、GeoJSONデータを索引付けするOracle Spatial and Graph索引を指定します。空間索引仕様には spatialフィールドがあり、その値は索引付けするJSONフィールドへのパスを指定する文字列です。対象となるJSONフィールドの値は、単一のGeoJSON geometryオブジェクト、つまりGeoJSON geometryオブジェクトでもあるJSONスカラーである必要があります。

デフォルトのエラー処理動作では、ターゲット・フィールドの存在が必須ではなく、存在する場合、その値は単一のGeoJSON geometry オブジェクトである必要があります。索引付けするドキュメントについて、そうでない場合には索引付け時にエラーが発生します。さらに、このような索引が存在する場合に、そうではないドキュメントを書き込もうとすると、書込み操作のエラーが発生します。^脚注3

空間索引仕様では、true値を使用して次のいずれかのブール値を含めることで、デフォルトとは異なるエラー処理動作を指定できます。(trueとして指定できるのは、エラー処理フィールドの1つのみです。そうしないと、索引作成時に構文エラーが発生します。)

scalarRequired - ブール値。オプションです。ターゲット・フィールドが存在し、その値としてGeoJSON geometryオブジェクトを持つ必要があります。索引付けするドキュメントについて、そうでない場合には索引付け時にエラーが発生します。さらに、このような索引が存在する場合に、そうではないドキュメントを書き込もうとすると、書込み操作のエラーが発生します。^脚注4
lax — ブール値。オプションです。ターゲット・フィールドが存在する必要も、その値としてGeoJSON geometryオブジェクトを持つ必要もありません。索引付けするドキュメントの索引付け時に、フィールドが欠落しているか、またはフィールド値がジオメトリでないドキュメントの索引付け時にエラーは発生しません。さらに、このような索引が存在する場合に、そうではないドキュメントを書き込もうとしても、書込み操作のエラーは発生しません。^脚注5

注意:

値がGeoJSON geometryオブジェクトであるフィールドに対してSODA空間索引を作成しており、そのフィールドをターゲットとするQBEを使用するとき、索引とQBEの両方がそのフィールドに対して同じエラー処理動作を指定している場合には、QBEに対してのみの索引を選択できます。どちらにも、次のうち同じものを指定する必要があります。

scalarRequired = true
lax = true
scalarRequired = trueでもlax = trueでもありません

検索索引仕様

SODA検索索引仕様では、JSON検索索引を指定します。これにより、JSONドキュメントのテキスト・コンテキストが一般的な方法で索引付けされます。検索索引によって、(1)非定型の構造的問合せ、つまり、定期的には予測または使用されない可能性のある問合せと、(2)全文検索を使用する問合せの両方のパフォーマンスを向上させることができます。これは、JSONデータでの使用に特化して設計されたOracle Text索引です。

JSON検索索引は、ドキュメントに関する集計情報を累積して更新することもできます。ここには、一連のJSONドキュメントに含まれる構造および型情報の概要を示す、JSON データ・ガイドが提供されています。これらの文書内で使用されているフィールドに関するメタデータを記録します。

データ・ガイド情報は、次の用途に使用できます。

JSONドキュメントのセットを記述するJSONスキーマ・ドキュメントを生成します。
ドキュメント内のデータに対してSQL操作を実行するために使用できるデータベース・ビューを作成します。
ドキュメント内の追加または変更されたフィールドに対応する仮想列を自動的に追加または更新します。

JSON検索索引に含まれるデータガイド情報は、新しいJSONコンテンツが追加されると自動的に更新されます。

デフォルトで、検索索引仕様が、これらの両方の機能を提供する索引(一般索引とデータ・ガイド)を作成します。これらの機能は、それぞれsearch_on(文字列)フィールドおよびdataguide(文字列)フィールドで指定されます。

フィールドsearch_onが値"none"で存在する場合、索引はデータ・ガイド機能のみを提供します(一般検索索引なし)。フィールドdataguideが値"off"で存在する場合、一般的な検索索引機能のみが提供されます(データ・ガイドのサポートなし)。(dataguide値が"on"の場合、またはフィールドdataguideがない場合は、データ・ガイドのサポートを指定します)。

none以外に、フィールドsearch_onは値"text"または"text_value"を持つこともできます。これらはどちらも、QBE演算子$containsを使用する全文問合せをサポートしています。また、いずれも、$eq、$neおよび$gtなどの他のQBE演算子を作成する非定型の問合せもサポートしています。

さらに、search_onの値"text_value"は数値の範囲に索引付けします。パフォーマンス・コストが追加されているため、これは別の値です。範囲の索引付けを必要としない場合は、text_valueのかわりに値textを指定することで、一部の索引メンテナンスの時間とディスク領域を節約できます。search_onのデフォルト値はtext_valueです。