Object の検索

Kii Cloud の Bucket 内 Object の取得には、条件を指定した検索が使用できます。たとえば「Bucket より "count" フィールドの値が 10 より大きい Object を、フィールド値降順で最大で 10 個取得」などといった条件に基づく Object の取得が可能です。

さまざまな検索の例については、検索のサンプルコード を参照してください。

Object 検索の実行

検索条件の指定

個々の検索条件は、KiiClause の以下のメソッドを用いて定義します。

メソッド 定義される検索条件
equals フィールド値が、指定の値に等しい場合にマッチ。
notEquals フィールド値が、指定の値に等しくない場合にマッチ。ただし指定したフィールド自体が存在しない場合はマッチしません。
greaterThan フィールド値が、指定の値より大きい場合にマッチ。
greaterThanOrEqual フィールド値が、指定の値以上の場合にマッチ。
lessThan フィールド値が、指定の値より小さい場合にマッチ。
lessThanOrEqual フィールド値が、指定の値以下の場合にマッチ。
startsWith フィールド値(String 型)が、指定の文字列により始まっている場合にマッチ。
inClause フィールド値が、指定の値のいずれかを持っている場合にマッチ。最大 200 件まで指定可能。JSON のフィールド型との一致が必要。
geoBox フィールド値(GeoPoint 型)が、指定の GeoBox(長方形エリア)の中に含まれる場合にマッチ。
geoDistance フィールド値(GeoPoint 型)が、指定の GeoDistance(円エリア)の中に含まれる場合にマッチ。
hasField フィールドが、指定の型である場合にマッチ。現在サポートされている型は STRINGINTEGERDECIMAL、および BOOLEAN です。

また複数の条件を結合するメソッドとして、次のものが利用可能です。

メソッド 定義される検索条件
and 複数の検索条件を AND で結合。
or 複数の検索条件を OR で結合。
not 複数の検索条件を NOT で結合。引数は KiiClause インスタンスで、単一条件の句か、and または or メソッドで結合した複数条件の句です。

KiiClause の詳細は JSDoc を参照してください。

not を含むクエリーでは、パフォーマンスが低下することがありますが、式の変形によって not の使用を回避できる場合があります。詳細は Not を含む式の変形 を参照してください。

クエリインスタンスの作成と検索の実行

KiiQuery インスタンスは queryWithClause メソッドに KiiClause インスタンスを渡すことで生成できます。KiiClause インスタンスを渡さずに KiiQuery インスタンスを生成した場合は、対象 Bucket 内の全ての Object が検索結果としてマッチします(i.e., all検索に相当)。

KiiQuery インスタンス作成後、さらにオプションとして以下のメソッドを用いて検索結果のソート順指定(1 フィールドのみサポート)や、一度に受け取る検索結果の件数上限を設定できます。

  • sortByAsc:指定フィールドをキーに昇順ソート。
  • sortByDesc:指定フィールドをキーに降順ソート。
  • setLimit:一度に返す検索結果の最大アイテム数(Best Effort の値)。最大値は 200。

クエリの詳細な仕様は以下のとおりです。

  • sortByAsc、sortByDesc のどちらも指定されなかった場合、検索結果のソート順は不定となります。setLimit が指定されなかった場合、一度の検索で受け取れる最大アイテム数は 200 となります。

  • パフォーマンスの最適化のため、指定した最大アイテム数 ≦ クエリにマッチする全件数 のとき、実際に返却される件数 = 指定した最大アイテム数 となることが保証されません。最大アイテム数分、存在していることが分かっていても、取得できた件数の確認は必要です。

  • 200 件以上取得する場合は、下記に示す ページネーション を利用して、複数回に分割して取得します。

  • sortByAsc、sortByDesc によるソートは、整数のフィールドはその値の大小で、文字列のフィールドは辞書順で行われます。

  • 格納されているフィールドの型が Object によって異なると正しく検索やソートができません。

  • 文字列のフィールドでは、値の大文字と小文字を区別して検索します。たとえば、クエリーの値 "alice" で、KiiObject オブジェクトの格納値 "Alice" を検索してもヒットしません。

  • 実数のフィールドでは、検索やソートが期待どおりに実行されない場合があります。実数のうち、小数点以下が 0 の値は整数として扱われます。例えば、1.0 は整数 1 として、1.1 は と実数 1.1 として、それぞれ異なる型でインデックスされます。これら、異なる型の間では大小関係が正しく評価されないため、期待した結果が得られません。実数での検索やソートを行いたい場合は、元の値を 10 倍、100 倍するなどして整数化したフィールドを保存し、そのフィールドを使ってクエリーを実行してください。

  • 検索対象となるフィールドは、Object の JSON 表現の第 1 階層だけです。ネストした Object のフィールドはインデックスされないため、深い階層にあるフィールドを検索してもヒットしません。

  • inClause を使う場合は、指定する値の型が Object に格納されている JSON の型と一致する点を確認してください。たとえば、{"id" : 123} は文字列 "123" ではマッチせず、数値 123 を指定しないと結果が得られません。また、値を複数指定する場合は同じ型しか指定できません。クエリに数値と文字列を混在させたり、小数を含む数値と含まない数値を混在させた検索はできません。

  • フィールド名は 250 文字まで、String 型の値は 190 文字まで検索できます。これらを超える長さのフィールド名や値を持つキーと値のペアは、このフィールドで検索してもヒットしません。

検索の実行は、作成したクエリインスタンスを指定して、検索対象 Bucket の executeQuery メソッドを実行することで行います。

KiiQuery の詳細は JSDoc を参照してください。

Object 数が多くなる場合、クエリーやソートによってパフォーマンスが低下する場合があります。対処方法のヒントは こちら をご覧ください。

検索における所定キーの使用

キーと値のペアとしてアプリから作成したデータ以外に、Kii Cloud によって自動的に生成された所定キーによる検索もできます。

所定キーは Object の作成や更新のタイミングで、自動的に作成または更新されます。

キー名 内容
_id Object の識別子です。自動的に割り当てられた値か、作成時に指定した値のどちらかになります。ID の値は Bucket 内だけで一意であることが保証されます。詳細は オブジェクトの ID と URI をご覧ください。
_owner Object 作成者のユーザーを表します。特に、Object の ACL で使用されます。
_created Object の作成日時(UNIX 時間、ミリ秒、UTC)です。
_modified Object の最終更新日時(UNIX 時間、ミリ秒、UTC)です。作成直後は _created と同じ値です。
_version Object のバージョン番号です。作成直後は 1 で、更新するたびに 1 ずつ増えます。更新の衝突が発生したことを検出するために、楽観的ロック で使用します。

Object 検索結果の取得

検索結果の取得

検索結果は、KiiObject の Array として返されます。検索結果が複数のページに渡っている場合(たとえば、setLimitで 10 を指定し、30 件のオブジェクトが一致した場合)、Kii Cloud は最初のページの検索結果とともに KiiQuery インスタンスを返します。次のページ以降の検索結果は、この KiiQuery を使って再度検索を実施することで取得できます。

ただし、サーバーから 1 回で返される件数とクエリ条件にマッチする件数が等しく、未取得の検索結果が存在しない場合に、SDK から未取得の結果が存在すると返される(nextQuery != null になる)可能性があります。次のページの取得時に、空の結果が取得されうることを前提にした実装が必要です。

Web のように一定件数ずつページングするような画面構成を実現したい場合、ページの管理は自分で行う必要があります。検索結果は、順方向にのみ取得でき、かつ、1 回の取得件数は Best Effort のため一定しません。先に Object の件数 を取得して、ページ管理に使用することもできます。