2 SODAフィルタ仕様(QBE)の概要

フィルタ仕様は、JSONで表されるパターンです。コレクションから、コンテンツが一致するJSONドキュメントを選択するために使用します。つまり、パターンで表される条件が、それらのドキュメント(のみ)のコンテンツに対してtrueと評価される場合です。

フィルタ仕様は、例による問合せ(QBE)または単にフィルタとも呼ばれます。

QBEはドキュメントをコレクションから選択するため、それらのドキュメントの読取りおよび書込み操作を決定するために使用できます。たとえば、QBEを使用して、一致するすべてのドキュメントをコレクションから削除できます。

例による問合せをサポートする各SODA実装には、JSONドキュメントを問い合せるための独自の方法が用意されています。これらはすべて、SODAフィルタ仕様を使用して問合せ対象のデータを定義します。たとえば、SODA for RESTでは、HTTP POSTリクエストを使用してURI引数action=queryを渡し、POST本体にフィルタ仕様を指定します。

QBEパターンは、フィールド値比較やフィールド存在のテストなどの演算を実行する条件演算子や、論理和($or)および論理積($and)のための論理組合せ演算子を含む演算子をこのドキュメントの選択または照合に使用します。

QBE演算子は、QBE内でJSONオブジェクトのフィールドとして発生します。関連付けられるフィールド値は、演算子が適用されるオペランドです。SODA演算子は、名前がドル記号$で始まる事前定義のフィールドです。

たとえば、次のQBEでは、フィールドageの値であるオブジェクトは、そのフィールドとして演算子$gtをフィールド値として持っており、関連するオペランドが数値45です。

{ "age" : { "$gt" : 45 } }

注意:

例による問合せは、異種コレクション(メディア・タイプ列を含むコレクション)ではサポートされていません。このようなコレクションは、JSONとJSON以外の両方のコンテンツの格納用に設計されています。QBEはJSONドキュメントのみを含むコレクションに対してのみサポートされます。

関連項目:

JSONについては、JSONの紹介を参照

• サンプルJSONドキュメント
  サンプルJSONドキュメントのいくつかをここで示します。これらは例による問合せ(QBE)の例および参照の説明で参照されています。
• SODA QBEにおけるパスの概要
  フィルタ仕様または例による問合せ(QBE)には、JSONドキュメントでのフィールドへのパスがゼロ個以上含まれています。フィールドへのパスは複数のステップを持つことができ、オブジェクトと配列の境界を越えることができます。
• QBE比較演算子の概要
  例による問合せ(QBE)の比較演算子は、特定のJSONオブジェクト・フィールドがなんらかの条件を満たすかどうかをテストします。
• QBE演算子$notの概要
  例による問合せ(QBE)の演算子$notは、暗黙的にAND演算される1つ以上の比較句を含むJSONオブジェクトであるオペランドの動作を否定します。
• QBE項目メソッド演算子の概要
  例による問合せ(QBE)項目メソッド演算子は、JSONオブジェクト・フィールド値をなんらかの方法で変更または変換する(または、単純に問合せ結果セットからフィルタ処理する)ために使用します。それ以外の方法でフィールド値に適用される他のQBE演算子では、かわりに変換されたフィールド値に適用されます。
• QBE論理組合せ演算子の概要
  例による問合せ(QBE)論理組合せ演算子($and、$orおよび$nor)は、条件を組み合せてさらに複雑なQBEを形成する場合に使用します。各演算子は条件の配列を引数として受け入れます。
• QBEにおけるネストされた条件の概要
  ネストされた条件を含む例による問合せ(QBE)を使用して、オブジェクト要素を含む配列値フィールドを持つドキュメントを照合できます。ここでは、配列の特定の要素が複数の基準を満たします。
• QBE演算子$idの概要
  通常、他の例による問合せ(QBE)演算子は、ドキュメント内で特定のJSONフィールドを検索して、その値を照合しようとします。演算子$idは、かわりにドキュメント・キーに一致するという点で例外です。したがって、ドキュメントのコンテンツではなくドキュメントのメタデータを照合します。QBEの最も外側の条件で演算子$idを使用します。
• QBE演算子$orderbyの概要
  例による問合せ(QBE)の演算子$orderbyについて説明しています。これは問合せ結果を昇順または降順にソートします。
• QBE空間演算子の概要
  例による問合せ(QBE)演算子$near、$intersectsまたは$withinを使用して、指定した位置に近いか、指定したジオメトリ・オブジェクトに交差する、または指定した別のジオメトリ・オブジェクト内にあるGeoJSONジオメトリ・オブジェクトを持つフィールドがあるドキュメントをそれぞれ選択できます。

2.1 サンプルJSONドキュメント

サンプルJSONドキュメントのいくつかをここで示します。これらは例による問合せ(QBE)の例および参照の説明で参照されています。

例2-1 サンプルJSONドキュメント1

{ "name"    : "Jason",  
  "age"     : 45,   
  "address" : [ { "street" : "25 A street", 
                  "city"   : "Mono Vista", 
                  "zip"    : 94088,
                  "state"  : "CA" } ],  
  "drinks"  : "tea" }

例2-2 サンプルJSONドキュメント2

{ "name"    : "Mary", 
  "age"     : 50, 
  "address" : [ { "street" : "15 C street", 
                  "city"   : "Mono Vista", 
                  "zip"    : 97090, 
                  "state"  : "OR" }, 
                { "street" : "30 ABC avenue", 
                  "city"   : "Markstown",
                  "zip"    : 90001, 
                  "state"  : "CA" } ] }

例2-3 サンプルJSONドキュメント3

{ "name"   : "Mark", 
  "age"    : 65, 
  "drinks" : ["soda", "tea"] }

2.2 SODA QBEにおけるパスの概要

フィルタ仕様または例による問合せ(QBE)には、JSONドキュメントでのフィールドへのパスがゼロ個以上含まれています。フィールドへのパスは複数のステップを持つことができ、オブジェクトと配列の境界を越えることができます。

(QBEにおいて、"フィールドへのパス"は、非公式に"フィールド"と短縮されることがあります。)

たとえば、次のQBEはzipフィールドがフィールドaddressに存在し、値が94088であるすべてのJSONドキュメントを照合します。

{ "address.zip" : 94088 }

前述のQBEのパスはaddress.zipであり、例2-1と一致しています。

注意:

SODA QBE自体はJSONオブジェクトです。QBEでは、厳密なJSON構文を使用する必要があります。具体的には、すべてのフィールド名を二重引用符(")で囲む必要があります。これには、SODAパスとして機能するaddress.zipなどのフィールド名が含まれます。たとえば、{"address.zip" : 94088}を記述する必要があります。{address.zip : 94088}ではありません。

パスは、角カッコ([および])で配列の要素の位置を囲むことにより、JSONドキュメント内の配列の特定の要素を対象にできます。

たとえば、パスaddress[1].zipは、配列addressesの2番目のオブジェクト内のすべてのzipフィールドを対象にします(配列の位置番号は1ではなく、0から始まります。)次のQBEは、address配列の2番目のオブジェクトに値が90001のzipフィールドが含まれているため、例2-2と一致します。

{ "address[1].zip" : 90001}

1つの配列位置を指定するかわりに、位置のリスト(例: [1,2])または位置の範囲(例: [1 to 3])を指定できます。次のQBEは、配列drinksの最初の要素(位置0)として"soda"が含まれているため、例2-3と一致します。

{ "drinks[0,1]" : "soda" }

また、次のQBEは、2番目または3番目の配列要素(位置1または2)として"soda"が含まれていないため、いずれのサンプル・ドキュメントとも一致しません。

{ "drinks[1 to 2]" : "soda" }

配列ステップを指定しない場合は、[*]が仮定されます。これはすべての配列要素と一致します。つまり、*はワイルドカードとして機能します。たとえば、フィールドdrinksの値が配列である場合、次のQBEはいずれかの配列要素の値が文字列"tea"の場合にドキュメントに一致するものを見つけます。

{"drinks" : "tea"}

このQBEはサンプル・ドキュメント1および2と一致します。明示的にワイルドカードを使用する同等のQBEは、次のようになります。

{"drinks[*]" : "tea"}

関連項目:

厳密なJSON構文および緩慢なJSON構文の詳細は、Oracle Database JSON開発者ガイドを参照

2.3 QBE比較演算子の概要

例による問合せ(QBE)の比較演算子は、指定されたJSONオブジェクト・フィールドがいくつかの条件を満たすかどうかをテストします。

最も単純で便利なフィルタ仕様の1つは、フィールドが特定の値と等しいかどうかをテストします。たとえば、次のフィルタ仕様はフィールドnameの値が"Jason"である任意のドキュメントを照合します。これは、フィールド値の等価性をテストするQBE演算子$eq,を使用します。

{ "name" : { "$eq" : "Jason" } }

便宜上、このようなスカラー等価QBEの場合、一般に、演算子$eqを省略できます。したがって、次のスカラー等価フィルタ仕様は$eqを使用する前述のフィルタ仕様と同じです。

{ "name" : "Jason" }

前述のフィルタ仕様の両方が例2-1と一致します。

比較演算子は、次のとおりです。

• $all - 配列フィールドの値がすべての値のセットを含むかどうか

• $between - フィールド値が2つの文字列または数値の間にあるかどうか(両端を含む)

• $eq - フィールド値が指定されたスカラーと等しいかどうか

• $exists - 指定されたフィールドが存在するかどうか

• $gt - フィールド値が指定されたスカラー値より大きいかどうか

• $gte - フィールド値が指定されたスカラー以上かどうか

• $hasSubstring - 文字列フィールド値に指定された部分文字列があるかどうか($instr $instrと同じかどうか)

• $in - フィールド値が指定されたスカラー値のセットのメンバーかどうか

• $instr - 文字列フィールド値に指定された部分文字列があるかどうか($hasSubstringと同じかどうか)

• $like - フィールド値が特定のSQL LIKEパターンと一致するかどうか

• $lt - フィールド値が指定されたスカラー値より小さいかどうか

• $lte - フィールド値が指定されたスカラー値以下であるかどうか

• $ne - フィールド値が指定されたスカラー値と異なるかどうか

• $nin - フィールド値が指定されたスカラー値のセットのメンバーでないかどうか

• $regex - 文字列フィールド値が指定された正規表現と一致するかどうか

• $startsWith - 文字列フィールド値が指定された部分文字列で始まるかどうか

1つのQBEフィールドの値であるオブジェクトで複数の比較演算子を組み合せることができます。演算子は暗黙的にAND演算されます。たとえば、次のQBEでは比較演算子$gtと$ltを使用します。例2-2と一致します。そのドキュメントに含まれるageフィールドの値が(50)であり、それが45より大きく、かつ55より小さいためです。

{ "age" : { "$gt" : 45, "$lt" : 55 } }

注意:

SODA演算子のオペランドも、QBEによってドキュメントで一致したデータも、JSONデータです。ただし、比較演算子では、比較の前にこのようなJSON値が特別に解釈される場合があります。項目メソッド演算子を使用すると、JSON文字列データを最初にたとえば大文字として、または日付またはタイムスタンプ(日付と時刻)として解釈するように指定できます。これは、項目メソッド演算子に関する項で説明されています。

2.4 QBE演算子$notの概要

例による問合せ(QBE)の演算子$notは、暗黙的にAND演算される1つ以上の比較句を含むJSONオブジェクトであるオペランドの動作を否定します。

これらの句のいずれかがfalseと評価された場合、それに$notを適用するとtrueと評価されます。すべてがtrueに評価されると、falseと評価されます。

たとえば、次のQBEでは例2-1および例2-3と一致します。ドキュメント1にはパスaddress.zipと一致するフィールドがあり、その値が"90001"ではありません。ドキュメント3にはパスaddress.zipと一致するフィールドがありません。

{"address.zip" : {"$not" : {"$eq" : "90001"}}}

次のQBEの$notオペランドには2つの比較句があります。これも例2-1および例2-3と一致します。それぞれ、値が46より大かつ、65より小、ではないageフィールドを持つためです。

{"age" : {"$not" : {"$gt" : 46, "$lt" : 65}}}

2.5 QBE項目メソッド演算子の概要

例による問合せ(QBE)項目メソッド演算子は、JSONオブジェクト・フィールド値に適用され、なんらかの方法でそれを変更または変換したり、単に問合せの結果セットからフィルタ処理します。例による問合せ(QBE)項目メソッド演算子は、JSONオブジェクト・フィールド値をなんらかの方法で変更または変換する(または、単純に問合せ結果セットからフィルタ処理する)ために使用します。それ以外の方法でフィールド値に適用される他のQBE演算子では、かわりに変換されたフィールド値に適用されます。

name値が"Joe"、"joe"、"JOE"、"joE"、"Joey"、"joseph"、"josé"などに一致するように、大/小文字の区別なく文字列値フィールドnameが"Jo"で始まるドキュメントを選択するとします。演算子$startsWithを使用できる可能性がありますが、文字列の接頭辞を文字どおりに照合して、Jとjを異なる文字とみなします。

ここで、項目メソッド演算子が役に立ちます。QBEでは、項目メソッド演算子$upperを使用して、"Joey"であれ"josé"であれ、実際に生のフィールド・データを大文字の文字列に変換してから演算子$startsWithを適用してテストできます。

次のQBEはフィールドの値nameの接頭辞に一致しますが、それを大文字に変換した後でのみ一致します。大文字の値は、JOで始まるという条件を使用して照合されます。

{ "name" : { "$upper" : { "$startsWith" : "JO" } } }

もう1つの例として、SODAでサポートされているISO 8601日時形式を使用する文字列値フィールドのdeadlineを持つドキュメントがあり、その期限が2019年1月31日午前7時(UTC)より前のドキュメントを選択するとします。項目メソッド演算子$timestampを使用すると、フィールドの文字値を(文字列ではなく),UTC時間の値に変換してから、$ltなどの演算子を使用して時間の比較を実行できます。次のQBEがこれを実行します。

{ "deadline" : { "$timestamp" : { "$lt" : "2019-01-31T07:00:00Z" } } }

これは、次のdeadlineフィールド値のそれぞれと一致します。QBEで指定された時刻より前の時刻を表しているためです。(最後の2つは正確に同じ時刻を表します。なぜなら、UTCから3時間遅れのタイム・ゾーンの午後7時はUTCの午後10時と同じであるためです)。

• { "deadline" : "2019-01-28T14:59:43Z" }

• { "deadline" : "2019-01-30T22:00:00Z" }

• { "deadline" : "2019-01-30T19:00:00–03:00" }

すべての項目メソッド演算子が、指定されたデータ型にデータを変換するわけではありません。他の種類の変換を実行するものもあります。たとえば、演算子$upperは文字列値を大文字に変換します。結果は文字列のままです。

項目メソッド演算子の中には、適用先のフィールド値とはまったく異なるデータを返すものもあります。たとえば、演算子$typeは、フィールド値のJSONデータ型の名前を指定する文字列値を返します。

したがって、たとえば次のQBEは、値が配列(["soda", "tea"])であるdrinksフィールドを持つ唯一のサンプルであるため、3つのサンプル・ドキュメントのうち例2-3のみを選択します。特に、たとえそのドキュメントがフィールドdrinksを持っていても、例2-1と一致しません。そのフィールドの値が配列ではなくスカラーの文字列"tea"であるためです。

{ "drinks" : { "$type" : "array" } }

注意:

項目メソッド・フィールド(演算子)自体は、関連する値(そのオペランド)を使用または処理しません。かわりに、その親フィールドと一致するJSONデータの値に作用します。

たとえば、QBE {"birthday" : {"$date" : {"$gt" : "2000-01-01"}}}で、項目メソッド演算$dateは親フィールドbirthdayと一致するJSONデータに作用します。JSONオブジェクト(この場合は比較句) {"$gt" : "2000-01-01"}であるオペランドを使用したり作用することはありません。JSONドキュメント内の誕生日データ(ISO 8601形式のJSON文字列)は日付として解釈され、その日付が、(ISO日付)文字列"2000-01-01" (2000年1月1日以降)で示された日付よりも大きいという条件と照合されます。

これには慣れるまでに少し時間がかかる可能性があります。オペランドは、項目メソッド演算子がジョブを実行した後に使用されます。これは、その親フィールドの値に対する演算子のアクションの結果と照合されます。項目メソッド演算子は一種のフィルタで、作用するデータと一致するフィールド(左側)と(その右側の)アクションの結果に適用されるいくつかのテストの間を構文的に表しています。

注意:

• 項目メソッド演算子$abs、$date、$size、$timestampまたは$typeを使用するには、Oracle Databaseリリース18c以上が必要です。

• 他の項目メソッドを使用するには、Oracle Databaseリリース12c (12.2.0.1)以上が必要です。

2.6 QBE論理組合せ演算子の概要

例による問合せ(QBE)論理組合せ演算子($and、$orおよび$nor)は、条件を組み合せてさらに複雑なQBEを形成する場合に使用します。各演算子は条件の配列を引数として受け入れます。

配列引数内の各条件がドキュメントと一致する場合に、QBE論理組合せ演算子$andは一致するドキュメントを見つけます。たとえば、次のQBEは例2-1と一致します。このドキュメントに値が"Ja"で始まるフィールドnameが含まれ、かつ、値が"tea"であるフィールドdrinksが含まれているためです。

{"$and" : [ {"name" : {"$startsWith" : "Ja"}}, {"drinks" : "tea"} ]}

多くの場合、演算子$andは省略可能、つまり暗黙的です。たとえば、次の問合せは前述の問合せと同等です。

{"name" : {"$startsWith" : "Ja"}, "drinks" : "tea"}

配列引数内の少なくとも1つの条件がドキュメントと一致する場合に、QBE論理組合せ演算子$orは一致するを見つけます。

たとえば、次のQBEは例2-2および例2-3と一致します。このドキュメントには、値が"soda"であるフィールドdrinksが含まれているか、あるいは、フィールドaddressの下にaddress.zipの値が94000未満のzipが含まれているか、またはその両方が含まれているためです。

{"$or" : [ {"drinks" : "soda"}, {"address.zip" : {"$le" : 94000}} ]}

QBE論理組合せ演算子$norは、配列引数内の条件がドキュメントと一致しない場合にドキュメントと一致します。(演算子$norおよび$orは論理補数演算子です。)

次の問合せは、サンプル・ドキュメント1と一致します。このドキュメントには値が"soda"であるフィールドdrinksがなく、フィールドaddressの下にaddress.zipの値が94000未満であるフィールドzipもどちらもないためです。

{"$nor" : [ {"drinks" : "soda"}, {"address.zip" : {"$le" : 94000}} ]}

論理組合せ演算子の配列引数内の各要素は条件です。

たとえば、次の条件には演算子$andを指定した論理組合せ句が1つあります。$andの配列値には2つの条件があります。最初の条件はフィールドageの値を制限します。2番目の条件には$orを指定した論理組合せ句が1つあり、フィールドnameの値またはフィールドdrinksの値を制限します。

{ "$and" : [ { "age" : {"$gte" : 60} },
             { "$or" : [ {"name" :  "Jason"},
                         {"drinks" : {"$in" : ["tea", "soda"]}} ] } ] }

• フィールドageの比較を含む条件はサンプル・ドキュメント3と一致します。

• 論理組合せ演算子$orを含む条件はサンプル・ドキュメント1および3と一致します。

• 条件全体はサンプル・ドキュメント3のみと一致します。このドキュメントのみがageの条件および$orを使用する条件の両方を満たすドキュメントであるためです。

次の条件は、演算子$orの配列引数内に2つの条件があります。最初の条件には$andを指定した論理組合せ句が1つあり、フィールドnameおよびdrinksの値を制限します。2番目の条件には$norを指定した論理組合せ句が1つあり、フィールドageおよびnameの値を制限します。

{ "$or" : [ { "$and" : [ {"name" : "Jason"},
                         {"drinks" : {"$in" : ["tea", "soda"]}} ] },
            { "$nor" : [ {"age" : {"$lt" : 65}},
                         {"name" : "Jason"} ] } ] }

• 演算子$andを含む条件はサンプル・ドキュメント1と一致します。

• 演算子$norを含む条件はサンプル・ドキュメント3と一致します。

• 条件全体はサンプル・ドキュメント1と3の両方と一致します。これらのドキュメントがそれぞれ、$or引数内の少なくとも1つの条件を満たすためです。

2.7 QBEでネストされた条件の概要

ネストされた条件を含む例による問合せ(QBE)を使用して、オブジェクト要素を含む配列値フィールドを持つドキュメントを照合できます。ここでは、配列の特定の要素が複数の基準を満たします。

次の条件は、配列addressの下の同じオブジェクトでcity値が"Mono Vista"でstate値が"CA"のドキュメントを見つけます。

{"address" : { "city" : "Mono Vista", "state" : "CA"}}

これは、親フィールドaddressが必要であることを示します。そのフィールドの値が配列の場合、配列内の少なくとも1つのオブジェクトに、値が"Mono Vista"のcityフィールドおよび値が"CA"のstateフィールドが必要です。3つのサンプルJSONドキュメントのうち、このQBEは例2-1のみと一致します。

次のQBEもサンプル・ドキュメント1と一致しますが、例2-2とも一致します。

{"address.city" : "Mono Vista", "address.state" : "CA"}

前述のQBEとは異なり、ここではcityとstateが同じアドレスに属する必要があるという制限がありません。かわりに、このQBEでは、一致するドキュメントにaddress配列のオブジェクトに値が"Mono Vista"のcityフィールドおよびaddress配列のオブジェクトに値が"CA"のstateフィールドが必要であることのみを指定します。フィールドaddress.cityおよびaddress.stateが同じオブジェクトに存在する必要があることを指定しているわけではありません。

2.8 QBE演算子$idの概要

通常、他の例による問合せ(QBE)の演算子はドキュメント内で特定のJSONフィールドを検索し、その値を照合しようとします。演算子$idは、かわりにドキュメント・キーに一致するという点で例外です。したがって、ドキュメントのコンテンツではなくドキュメントのメタデータを照合します。QBEの最も外側の条件で演算子$idを使用します。

例2-4に、演算子$idを使用する3つのQBEを示します。

例2-4 $idを使用した特定のキーを持つドキュメントの検索

// Find the unique document that has key "key1".
{"$id" : "key1"}

// Find the documents that have any of the keys "key1", "key2", and "key3".
{"$id" : ["key1","key2","key3"]}

// Find the documents that have at least one of the keys "key1" and "key2",
// and that have an object with a field address.zip whose value is at least 94000.
{"$and" : [{$id : ["key1", "key2"]},
           {"address.zip" : { "$gte" : 94000 }}]}

2.9 QBE演算子$orderbyの概要

例による問合せ(QBE)の演算子$orderbyについて説明します。これは問合せ結果を昇順または降順にソートします。

個々のフィールドのソート順と、フィールド間の相対的なソート順を指定できます。

演算子$orderbyは、配列と省略の2つの構文で使用できます。

構文の選択にかかわらず、フィルタ仕様で演算子$orderbyを1つ以上のフィルタ条件とともに使用した場合、これらの条件を演算子$queryでラップする必要があります。ここに示した問合せで、返されるドキュメントは、フィールドageの値が40より大きい値である必要があることを指定したフィルタ条件を満たすドキュメントに限定されます。

Orderby句の配列構文の使用

配列構文は、2つのうち単純なほうの構文です。$orderbyの後には、ソートするフィールドの配列を、相対的なソート順で続けます。つまり、配列の最初の要素はソートする最初のフィールド、2番目の要素はソートする2番目のフィールド、のように指定します。

配列構文を使用すると、ソートの目的で、特定のフィールドのソートに使用するSQLデータ型、つまりフィールド値の解釈方法を指定することもできます。

たとえば、(文字列または数値として)数値コードを持つフィールドを、辞書順に(数字の文字列として)ソートするか、数値として解釈された数字の連続として数値でソートするかを指定できます。データ・ソート・タイプとして"varchar2"を指定すると、昇順で"100"は"9"の前にソートされます。ソート・タイプとして"number"を指定すると、昇順で"9"は"100"の前にソートされます。数値90は数値100より小さいためです。

注意:

dateまたはtimestampのdatatype値を使用するには、Oracle Databaseリリース18c以上が必要です。

最後に、文字列値フィールド配列構文には、文字列の先頭で最大文字数を指定することもできます。ターゲット・フィールドの文字列値が長すぎる場合、エラーが発生します。(長すぎる文字列はソート時に無視されます。)

次のQBEでは、フィールドsalaryが10,000以上20,000以下であるオブジェクトが選択されます。オブジェクトは、まず数値として解釈されてageの降順でソートされ、次に文字列として解釈されてnameの昇順でソートされます。一致するドキュメントでフィールドnameの文字列値が100文字を超える場合、エラーが発生します。ここではデフォルトのエラー処理が適用されます。いずれかのフィールドの値が、指定されたdatatypeに変換できない場合、エラーが発生しますが、指定されたフィールドのいずれかがない場合、エラーは発生しません。

{ "$query"   : { "salary" : { "$gt" : 10000, "$lte" : 20000 } },
  "$orderby" : [ { "path" : "age", "datatype" : "number", "order" : "desc" },
                 { "path" : "name", "datatype" : "varchar2", "order" : "asc",
                  "maxLength" : 100 } ] }

次のQBEは同じです。ただし、一致する各ドキュメントにフィールドnameが存在する必要があります(その値が文字列に変換可能であることも条件です)。それ以外の場合は、問合せ時にエラーが発生します。

{ "$query"   : { "salary" : { "$gt" : 10000, "$lte" : 20000 } },
  "$orderby" : { "$fields" :
                 [ { "path" : "age", "datatype" : "number", "order" : "desc" },
                   { "path" : "name", "datatype" : "varchar2", "order" : "asc",
                     "maxLength" : 100 } ],
                 "$scalarRequired" : true } }

Orderby句の省略構文の使用

省略構文を使用すると、ソートするフィールドとその相対的なソート順を順番にリストできます。ソートの目的で特定のフィールドの値を解釈する方法(つまり、値をどのデータ型として解釈するか)を指定することはできません。また、文字列フィールドのソート時に考慮する最大文字数も指定できません。

次のQBEでは、salaryが10,000から20,000の間であるドキュメントをソートするときのフィールドageとnameの順序を指定します。値に–1を指定すると、ageを昇順にソートします。値に2を指定すると、nameを昇順にソートします。ソートは、まずageを基準に、次にnameを基準に実行されます。これは、–1の絶対値が2の絶対値より小さいためであり、-1が2より小さいからでも、$orderbyオブジェクトでフィールドageがフィールドnameより先に出現するからでもありません。

{ "$query" : { "salary" : { $between [10000, 20000] } },
  "$orderby" :  { "age" : -1, "name" : 2 } }

2.10 QBE空間演算子の概要

例による問合せ(QBE)演算子$near、$intersectsまたは$withinを使用して、指定した位置に近いか、指定したジオメトリ・オブジェクトに交差する、または指定した別のジオメトリ・オブジェクト内にあるGeoJSONジオメトリ・オブジェクトを持つフィールドがあるドキュメントをそれぞれ選択できます。

注意:

QBE空間演算子を使用するには、Oracle Databaseリリース12c (12.2.0.1)以上が必要です。

次のQBEでは、locationフィールドの値がPoint GeoJSONジオメトリ・オブジェクトであり、座標[34.0162, -118.2019]から50キロメートル以内の位置にあることを表している場合に、そのlocationフィールドがあるドキュメントのみを選択します。

{ "location" :
  { "$near" :
    { "$geometry" : { "type" : "Point", "coordinates" : [34.0162, -118.2019] },
      "$distance" : 50,
      "$unit"     : "KM" } } }

たとえば、次のようなオブジェクトを含むドキュメントを取得できます。

{ "location" : { "type" : "Point", "coordinates": [33.7243, -118.1579] } }

locationフィールドを含まないドキュメントは、エラーを返さずに無視(スキップ)されます。ただし、問合せ対象のコレクションに、(単一の)GeoJSONジオメトリ・オブジェクトとして値を持たないlocationフィールドがあるドキュメントが含まれる場合は、エラーが発生します。たとえば、このオブジェクトのドキュメントでは、次のようなエラーが発生します。

{ "location" : "1600 Pennsylvania Ave NW, Washington, DC 20500" }

空間演算子$near、$intersectsまたは$withinの値であるオブジェクトに、trueに評価される$scalarRequiredまたは$laxフィールドを(ただし、両方同時にではなく)含めることで、異なる(デフォルト以外の)エラー処理動作をQBEに指定できます。

• フィールド$scalarRequiredの値がtrueの場合は、ドキュメントにlocationフィールドがなければエラーが発生します。(locationフィールドの値がジオメトリ・オブジェクトではない場合も、エラーが発生します。)

• フィールド$laxの値がtrueの場合、欠落したlocationフィールドのみでなく、値がGeoJSONジオメトリ・オブジェクトではないlocationフィールドも無視されます。

たとえば、あるドキュメントにlocationフィールドがない場合、またはそのドキュメントに値がジオメトリ・オブジェクトではないlocationフィールドがある場合、このQBEはエラーを生成します。

{ "location" :
  { "$near" :
    { "$geometry"      : { "type" : "Point", "coordinates" : [34.0162, -118.2019] },
      "$distance"      : 50,
      "$unit"          : "KM",
      "$scalarRequired : true } } }

また、locationフィールドがないドキュメント、または値がジオメトリ・オブジェクトではないlocationフィールドがあるドキュメントに対して、このQBEはエラーを発生しません。

{ "location" :
  { "$near" :
    { "$geometry" : { "type" : "Point", "coordinates" : [34.0162, -118.2019] },
      "$distance" : 50,
      "$unit"     : "KM",
      "$lax"      : true } } }

注意:

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

• scalarRequired = true

• lax = true

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