KiiObject の検索
Kii Cloud の Bucket 内 KiiObject の取得には、条件を指定した検索が使用できます。たとえば「Bucket より "count" フィールドの値が 10 より大きい KiiObject を、フィールド値降順で最大で 10 個取得」などといった条件に基づく KiiObject の取得が可能です。
さまざまな検索の例については、検索のサンプルコード を参照してください。
KiiObject 検索の実行
検索条件の指定
個々の検索条件は、KiiClause の以下のメソッドを用いて定義します。
| メソッド | 定義される検索条件 |
|---|---|
| equals() | フィールド値が、指定の値に等しい場合にマッチ。 |
| notEquals() | フィールド値が、指定の値に等しくない場合にマッチ。ただし指定したフィールド自体が存在しない場合はマッチしません。 |
| greaterThan() | フィールド値が、指定の値より大きい場合にマッチ。 |
| greaterThanOrEqual() | フィールド値が、指定の値以上の場合にマッチ。 |
| lessThan() | フィールド値が、指定の値より小さい場合にマッチ。 |
| lessThanOrEqual() | フィールド値が、指定の値以下の場合にマッチ。 |
| startsWith() | フィールド値（String 型）が、指定の文字列により始まっている場合にマッチ。 |
| inClause() | フィールド値が、指定の値のいずれかを持っている場合にマッチ。最大 200 件まで指定可能。JSON のフィールド型との一致が必要。 |
| geoBox() | フィールド値（GeoPoint 型）が、指定の GeoBox（長方形エリア）の中に含まれる場合にマッチ。 |
| geoDistance() | フィールド値（GeoPoint 型）が、指定の GeoDistance（円エリア）の中に含まれる場合にマッチ。 |
| hasField() | フィールドが、指定の型である場合にマッチ。現在サポートされている型は STRING、INTEGER、DECIMAL、および BOOLEAN です。 |
また複数の条件を結合するメソッドとして、次のものが利用可能です。
| メソッド | 定義される検索条件 |
|---|---|
| and() | 複数の検索条件を AND で結合。 |
| or() | 複数の検索条件を OR で結合。 |
| not() | 複数の検索条件を NOT で結合。引数は KiiClause インスタンスで、単一条件の句か、and() または or() メソッドで結合した複数条件の句です。 |
KiiClause クラスの詳細は JSDoc を参照してください。
not を含むクエリーでは、パフォーマンスが低下することがありますが、式の変形によって not の使用を回避できる場合があります。詳細は Not を含む式の変形 を参照してください。
クエリインスタンスの作成と検索の実行
KiiQuery インスタンスは queryWithClause() メソッドに KiiClause インスタンスを渡すことで生成できます。KiiClause インスタンスを渡さずに KiiQuery インスタンスを生成した場合は、対象 Bucket 内の全ての KiiObject が検索結果としてマッチします（i.e., all検索に相当）。
KiiQuery インスタンス作成後、さらにオプションとして以下のメソッドを用いて検索結果のソート順指定や、一度に受け取る検索結果の件数上限を設定できます。
- sortByAsc()：指定フィールドをキーに昇順ソート。
- sortByDesc()：指定フィールドをキーに降順ソート。
- setLimit()：一度に返す検索結果の最大アイテム数（Best Effort の値）を設定。最大値は 200。
クエリの詳細な仕様は以下のとおりです。
検索結果のソートには 1 フィールドのみを指定できます。
sortByAsc()メソッドとsortByDesc()メソッドのどちらも指定しない場合、検索結果のソート順は不定となります。setLimit()メソッドを実行しない場合、一度の検索で受け取れる最大アイテム数は 200 となります。パフォーマンスの最適化のため、指定した最大アイテム数 ≦ クエリにマッチする全件数 のとき、実際に返却される件数 ＝ 指定した最大アイテム数となることが保証されません。最大アイテム数分、存在していることが分かっていても、取得できた件数の確認は必要です。
200 件以上取得する場合は、下記に示す ページネーション を利用して、複数回に分割して取得します。
sortByAsc()メソッドとsortByDesc()メソッドによるソートは、整数のフィールドはその値の大小で、文字列のフィールドは辞書順で行われます。格納されているフィールドの型が KiiObject によって異なると正しく検索やソートができません。
文字列のフィールドでは、値の大文字と小文字を区別して検索します。たとえば、クエリーの値 "alice" で、KiiObject の格納値 "Alice" を検索してもヒットしません。
実数のフィールドでは、検索やソートが期待どおりに実行されない場合があります。実数のうち、小数点以下が 0 の値は整数として扱われます。例えば、1.0 は整数 1 として、1.1 は と実数 1.1 として、それぞれ異なる型でインデックスされます。これら、異なる型の間では大小関係が正しく評価されないため、期待した結果が得られません。実数での検索やソートを行いたい場合は、元の値を 10 倍、100 倍するなどして整数化したフィールドを保存し、そのフィールドを使ってクエリーを実行してください。
検索対象となるフィールドは、KiiObject の JSON 表現の第 1 階層だけです。ネストした KiiObject のフィールドはインデックスされないため、深い階層にあるフィールドを検索してもヒットしません。
inClause()メソッドを使う場合は、指定する値の型が KiiObject に格納されている JSON の型と一致する点を確認してください。たとえば、{"id" : 123}は文字列 "123" ではマッチせず、数値 123 を指定しないと結果が得られません。また、値を複数指定する場合は同じ型しか指定できません。クエリに数値と文字列を混在させたり、小数を含む数値と含まない数値を混在させた検索はできません。フィールド名は 250 文字まで、String 型の値は 190 文字まで検索できます。これらを超える長さのフィールド名や値を持つキーと値のペアは、このフィールドで検索してもヒットしません。
検索の実行は、作成したクエリインスタンスを指定して、検索対象 Bucket の executeQuery() メソッドを実行することで行います。
KiiQuery クラスの詳細は JSDoc を参照してください。
KiiObject 数が多くなる場合、クエリーやソートによってパフォーマンスが低下する場合があります。対処方法のヒントは パフォーマンス をご覧ください。
検索における所定キーの使用
キーと値のペアとしてアプリから作成したデータ以外に、Kii Cloud によって自動的に生成された所定キーによる検索もできます。
所定キーには、KiiObject の ID や作成日時などの様々なフィールドがあります。所定キーの一覧は、所定キー を参照してください。
KiiObject 検索結果の取得
検索結果は、KiiObject の Array として返されます。検索結果が複数のページに渡っている場合（たとえば、setLimitで 10 を指定し、30 件のオブジェクトが一致した場合）、Kii Cloud は最初のページの検索結果とともに KiiQuery インスタンスを返します。次のページ以降の検索結果は、この KiiQuery を使って再度検索を実施することで取得できます。
ただし、サーバーから 1 回で返される件数とクエリ条件にマッチする件数が等しく、未取得の検索結果が存在しない場合に、SDK から未取得の結果が存在すると返される（nextQuery != null になる）可能性があります。次のページの取得時に、空の結果が取得されうることを前提にした実装が必要です。
Web のように一定件数ずつページングするような画面構成を実現したい場合、ページの管理は自分で行う必要があります。検索結果は、順方向にのみ取得でき、かつ、1 回の取得件数は Best Effort のため一定しません。先に KiiObject の件数 を取得して、ページ管理に使用することもできます。