2 SODAフィルタ仕様(QBE)の概要
フィルタ仕様は、JSONで表されるパターンです。コレクションから、コンテンツが一致するJSONドキュメントを選択するために使用します。つまり、パターンで表される条件が、それらのドキュメント(のみ)のコンテンツに対してtrueと評価される場合です。
フィルタ仕様は、例による問合せ(QBE)または単にフィルタとも呼ばれます。
QBEはドキュメントをコレクションから選択するため、それらのドキュメントの読取りおよび書込み操作を決定するために使用できます。たとえば、QBEを使用して、一致するすべてのドキュメントをコレクションから削除できます。
例による問合せをサポートする各SODA実装には、JSONドキュメントを問い合せるための独自の方法が用意されています。これらはすべて、SODAフィルタ仕様を使用して問合せ対象のデータを定義します。たとえば、SODA for RESTでは、HTTP POSTリクエストを使用してURI引数action=query
を渡し、POST本体にフィルタ仕様を指定します。
ノート:
一般に、例による問合せ(QBE)は、JSONドキュメントの問合せ用です。QBE演算子$id
および$textContains
は、異種コレクション(メディア・タイプ列を含むコレクション)で例外的に使用できます。演算子$textContains
は、異種コレクションでのみ使用できます。(異種コレクションにはJSONドキュメントを含めることができますが、必要ではありません。)
SODA for JavaおよびSODA for RESTでは、演算子$textContains
はサポートされず、異種コレクションで使用するための演算子$id
もサポートされません。
QBEパターンは、フィールド値比較やフィールド存在のテストなどの演算を実行する条件演算子や、論理和($or
)および論理積($and
)のための論理組合せ演算子を含む演算子をこのドキュメントの選択または照合に使用します。
QBE演算子は、QBE内でJSONオブジェクトのフィールドとして発生します。関連付けられるフィールド値は、演算子が適用されるオペランドです。SODA演算子は、名前がドル記号$
で始まる事前定義のフィールドです。
たとえば、次のQBEでは、フィールドage
の値であるオブジェクトは、そのフィールドとして演算子$gt
をフィールド値として持っており、関連するオペランドが数値45
です。
{ "age" : { "$gt" : 45 } }
QBE演算子には様々な種類があります。特に、次のような操作を行う演算子があります。(これは、QBE演算子の完全なリストではありません。)
-
フィールド値が存在するかどうか、または特定の値との比較方法をテストします。
これには、比較演算子
$all
、$between
、$eq
、$exists
、$gt
、$gte
、$hasSubstring
、$in
、$instr
、$like
、$lt
、$lte
、$ne
、$nin
、$regex
および$startsWith
が含まれます。たとえば、このQBEでは演算子
$gt
を使用して、フィールドage
の値が50
より大きいかどうかをテストします。{ "age" : { "$gt" : 50 } }
-
GeoJSONフィールド値の空間(地理またはジオメトリ)プロパティをテストします。
これには、演算子
$near
、$intersects
および$within
が含まれます。たとえば、このQBEでは、演算子
$near
を使用して、フィールドlocation
の値が、特定の$geometry
値(ここでは省略)の60マイル以内かどうかをテストします。{ "location" { "$near" : {"$geometry" : {...}, "$distance" : 60} } }
-
全文検索: フィールド値が、特定の文字列または数値とパターン一致するかどうかをテストします。
これは、QBE演算子
$contains
を使用します。たとえば、このQBEは、フィールド
name
の値に"beth"
という語が含まれているかどうかをテストします。{ "name" : { "$contains" : "beth" } }
-
条件を論理的に組み合せます。
これには、演算子
$not
、$and
、$or
および$nor
が含まれます。たとえば、このQBEは、値が50を上回らないフィールド
age
、または値が10000
であるフィールドsalary
のいずれか(または両方)と一致します。{ "$or" : [ { "$not" {"age":{"$gt":50} }, { "salary" : {"$eq":10000} } ] }
-
QBE問合せで選択したオブジェクトをソートします。
これは、QBE演算子
$orderby
を、ソート対象のオブジェクトを選択するQBEを提供する演算子$query
とともに使用します。たとえば、このQBEでは、最初に、フィールド
salary
の値が10,000より大きいすべてのオブジェクトが選択されます。次に、演算子$orderby
を使用して、これらのオブジェクトがフィールドname
の値の昇順でソートされます。ソートする値は、文字列(データ型VARCHAR2
)として解釈されます。{ "$query" : {"salary":{"$gt":10000}}, "$orderby" : [ { "path" : "name", "datatype" : "varchar2" } ] }
-
一致した値に作用して、その場所でテストされた値を生成します。
これには、項目メソッドの演算子
$abs
、$boolean
、$ceiling
、$date
、$double
、$floor
、$length
、$lower
、$number
、$size
、$string
、$timestamp
、$type
および$upper
が含まれます。たとえば、次のQBEでは、項目メソッド
$date
は、フィールドbirthday
の値をdate値として解釈します。その後、この値がISO 8601文字列"2000-01-01"
で表される日付よりも大きい(後である)かどうかがテストされます。大きい場合、フィールド値は一致とみなされます。次より大きいのテストでは、フィールド値に作用する$date
からの結果として生成される、解釈された値が使用されます。{ "birthday" : { "$date" : {"$gt":"2000-01-01"} } }
関連項目:
-
JSONについては、JSONの紹介を参照
-
GeoJSONのJSON地理的データについては、GeoJSON.orgを参照
- サンプル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ジオメトリ・オブジェクトを持つフィールドがあるドキュメントをそれぞれ選択できます。 - QBE演算子$containsの概要
例による問合せ(QBE)の演算子$contains
は、SODAコレクション内のJSONドキュメントの全文検索を実行します。 - QBE演算子$textContainsの概要
例による問合せ(QBE)の演算子$textContains
は、異種SODAコレクション(メディア・タイプ列を持つコレクション)内のドキュメントの全文検索を実行します。
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"] }
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
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"}
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
- フィールド値が特定のSQLLIKE
パターンと一致するかどうか -
$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}}}
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
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)以上が必要です。
親トピック: SODAフィルタ仕様(QBE)の概要
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つの条件を満たすためです。
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
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にも一致します。この例には2つのaddressがあり、1つはcityのMono Vista、もう1つはstateのCAです。
{ "address.city" : "Mono Vista", "address.state" : "CA" }
ネストされた条件句を使用する前述のQBEとは異なり、ここではcityとstateが同じaddress
に属する必要があるという制限がありません。かわりに、このQBEでは、一致するドキュメントにaddress
フィールドのオブジェクトの子に値が"Mono Vista"
のcity
フィールドおよび同じaddress
フィールドのオブジェクトに値が"CA"
のstate
フィールドが必要であることのみを指定します。フィールドaddress.city
およびaddress.state
が同じオブジェクトに存在する必要があることを指定しているわけではありません。
最後のQBEは、[*]
がないネストされた条件句の形式を持つ次のQBEと同等です。
{ "address" : { "city" : "Mono Vista", "state" : "CA" } }
配列内のオブジェクトに複数の条件を適用する場合は、必ず[*]
を使用してください。
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
2.8 QBE演算子$idの概要
通常、他の例による問合せ(QBE)の演算子はドキュメント内で特定のJSONフィールドを検索し、その値を照合しようとします。演算子$id
は、かわりにドキュメント・キーに一致するという点で例外です。したがって、ドキュメントのコンテンツではなくドキュメントのメタデータを照合します。QBEの最も外側の条件で演算子$id
を使用します。
例2-4に、演算子$id
を使用する3つのQBEを示します。
例2-4 $idを使用した特定のキーを持つドキュメントの検索
キーkey1
を持つ一意のドキュメントを検索します。
{"$id" : "key1"}
key1
、key2
およびkey3
のいずれかのキーを持つドキュメントを検索します。
{"$id" : ["key1","key2","key3"]}
key1
およびkey2
の少なくとも1つのキーがあり、値が94000
以上のフィールドaddress.zip
を持つオブジェクトがあるドキュメントを検索します。
{"$and" : [{$id : ["key1", "key2"]},
{"address.zip" : { "$gte" : 94000 }}]}
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
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"
の前にソートされます。数値9
は数値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は同じですが、scalarRequired = true
が指定されている点が異なり、フィールド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 } }
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
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
も指定しない
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要
2.11 QBE演算子$containsの概要
例による問合せ(QBE)の演算子$contains
は、SODAコレクション内のJSONドキュメントの全文検索を実行します。
値が$contains
演算子を含むオブジェクトであるQBEフィールドは、JSONドキュメントのフィールドにフルワード文字列の値またはフル数値の値が含まれ、これが配列要素内を含む$contains
のどこかの文字列オペランドと一致する場合に、このJSONドキュメントと一致します。一致はOracle Textの全文です。
演算子$contains
の検索パターン値の構文は、SQL条件json_textcontains
の3番目のパラメータと同じであり、結果の動作が同じです。これは、たとえば、他のテキストの近くにあるテキストを問い合せたり、問合せでファジー・パターン・マッチングを使用できることを意味します。(検索パターン引数に、Oracle Textの検索で予約されている文字または単語が含まれる場合は、その文字または単語をエスケープする必要があります。)
$contains
で全文検索を使用するには、ドキュメント・コレクションのJSON検索索引を作成する必要があります。そのためには、例3-3のように、選択したSODA実装(言語)の索引作成関数またはメソッドに検索索引仕様を渡します。
コレクションの検索索引を作成すると、この単純なQBEでは、すべてのドキュメントのstreet
フィールドで"abc"
という語を含む値が大/小文字を区別せずに検索されます。
{"street" : { "$contains" : "abc"}}
たとえば、例2-2は値"30 ABC avenue"
を持つstreet
フィールドがあるため、一致します。
2.12 QBE演算子$textContainsの概要
例による問合せ(QBE)の演算子$textContains
は、異種SODAコレクション(メディア・タイプ列を持つコレクション)内のドキュメントの全文検索を実行します。
これを使用して、全文検索パターンに一致するテキストを含む非JSONドキュメントを検索できます。たとえば、Microsoft Word、Portable Document Format (PDF)およびプレーン・テキストのドキュメントはすべて、$textContains
を使用して全文検索できます。
($textContains
をJSONドキュメントで使用することもできますが、JSONドキュメントのみのコレクションの場合は演算子$contains
をお薦めします。演算子$contains
は異種コレクション用ではありません。)
演算子$textContains
の検索パターン値の構文は、SQL関数contains
で使用されるものと同じであり、結果の動作が同じです。これは、たとえば、他のテキストの近くにあるテキストを問い合せたり、問合せでファジー・パターン・マッチングを使用できることを意味します。(検索パターン引数に、Oracle Textの検索で予約されている文字または単語が含まれる場合は、その文字または単語をエスケープする必要があります。)
演算子$textContains
を使用するには、まず、検索対象となる異種コレクションの基礎となるデータベース表のOracle Text検索索引を作成する必要があります。次のSQLコードは、表myTextCollectionTable
のコンテンツ列myContentColumn
に検索索引mySearchIndex
を作成します。
CREATE SEARCH INDEX mySearchIndex ON
myTextCollectionTable(myContentColumn)
Oracle Databaseリリース21cより前には、次のより詳細な構文が必要です。
CREATE INDEX mySearchIndex ON
myTextCollectionTable(myContentColumn)
INDEXTYPE IS CTXSYS.CONTEXT
コレクションの検索索引がある場合、次の簡単なQBEはテキストIs it about a bicycle?
を検索します。
{"$textContains" : "Is it about a bicycle?"}
ノート:
演算子$textContains
は、SODA for JavaまたはSODA for RESTではサポートされません。
$textContains
をSODA for PL/SQLで使用するには、Oracle Databaseリリース21c (21.3)以上が必要です。
$textContains
をSODA for C、SODA for Node.jsまたはSODA for Pythonで使用するには、対応する21.3クライアント・ライブラリが必要です。
関連トピック
親トピック: SODAフィルタ仕様(QBE)の概要