8.3. オブジェクトのクエリ¶

GET /1/(tenantId)/objects/(bucketName)¶

オブジェクトをクエリする。

Request Headers:
	X-Application-Id -- アプリケーションID(必須) X-Application-Key -- アプリケーションキー(必須) X-Session-Token -- セッショントークン(オプション)
Parameters:	bucketName (string) -- バケット名
Query Parameters:
	where (string) -- 検索条件 order (string) -- ソート順序 skip (int) -- スキップカウント limit (int) -- 検索数上限。最大値およびデフォルト値は100件 count (int) -- 件数取得フラグ deleteMark (int) -- 1に設定すると論理削除されたデータもクエリ対象とする projection (string) -- プロジェクション readPreference (string) -- readPreference: 参照するDBの指定 timeout (int) -- クエリタイムアウト(ミリ秒)
Status Codes:	200 OK -- 正常終了 400 Bad Request -- パラメータ不正 401 Unauthorized -- 認証エラー 403 Forbidden -- 権限エラー 404 Not Found -- バケットが存在しない 500 Internal Server Error -- 検索条件・プロジェクションの演算子の利用方法が正しくない、その他のエラー 504 Gateway Timeout -- クエリタイムアウト
Response JSON Object:
	results (array) -- クエリ結果の配列 currentTime (string) -- サーバ時刻 count (int) -- 全件数 (countクエリパラメータを1に設定した場合のみ)

レスポンスボディの例

結果は以下のように results に配列形式で格納される。

また、"currentTime" にクエリ実行時のサーバ時刻が格納される(このフィールドはデータ同期処理を行う際に使用することを想定している)。

{
    "results": [
        {
          "_id":"52117490ac521e5637000001",
          "name":"Foo",
          "score":80,
          "ACL": { /* ACL */ }
          "createdAt": "2013-08-27T05:19:16.000Z",
          "updatedAt": "2013-08-27T05:19:16.000Z",
          "etag": "8c92c97e-01a7-11e4-9598-53792c688d1b"
        }
    ],
    "currentTime": "2013-09-01T12:34:56.000Z"
}

クエリの実行は、オブジェクトが暗号化されたままの状態で実施される。したがって、検索条件に "_protected" フィールドを指定した場合、暗号化されたデータに対して検索するため、期待する検索結果とならない。

注意事項

バケットcontentACLと対象オブジェクトの read 権限が必要
デフォルトの検索上限数は 100件である
クエリパラメータが非常に多い場合、ブラウザによっては URL の長さ制限のためにリクエストが発行できない場合がある。この場合はオブジェクトのロングクエリを使用すること。
検索条件はクエリパラメータ/URLに格納され、サーバのアクセスログに記録されるため、機密性の高い情報を格納するべきではない。やむを得ず検索式に含めたい場合は、オブジェクトのロングクエリを使用すること。
"_protected" フィールドを検索条件に指定した場合の動作は不定となる。

8.3.1. 検索条件¶

条件指定は where パラメータで指定する。where パラメータには、JSON で検索条件を設定する。

特定のキーに対して完全一致させたい場合は、以下のように指定する。

where={"name": "Foo"}

比較を行う場合は、以下の演算子を利用できる。

$lt, $gt : Less Than / Greater Than
$lte, $gte : Less or Equal / Greater of Equal
$ne : Not equal to

例) score が 70 超のものを選択したい場合

where={"score": {"$gt": 70}}

その他、以下の演算子を使用できる。これらは MongoDB の演算子と同じものがそのまま使用できる。

$in
$all
$regex
$exists
$not
$or
$and

8.3.2. ソート順序¶

順序指定は order パラメータで行う。order パラメータには、ソートを行うキー名を指定する。

以下の例は、age キー昇順でソートする。

order=age

複数条件を指定するときは "," で区切る。また、降順で検索したい場合は検索キーの前に "-" を付与する。以下の例は、第1優先で年齢昇順、第2優先で名前降順でソートする。

order=age,-name

注意

ソート対象のキー名の先頭が"-"(ハイフン)または、キー名に","(カンマ)が含まれる場合、正常にソートできない場合がある。

注意

ソート対象のキーにインデックスが設定されていない場合、MongoDB の制限により、ソート対象のデータ量は32MB以内に収める必要がある。この制限を超えると500 Internal Server Error となる。大量のデータをソートしたい場合は、必ずインデックスを設定すること。

8.3.3. スキップカウント(skip) / 検索数上限 (limit)¶

skip で検索結果の先頭からのスキップ数、limit で返却する検索数の上限を指定する。

以下の例では、検索結果の100件目から50件を取得する。

skip=100&limit=50

limit のデフォルト値は 100件とする。limit を指定しなかった場合は、デフォルトでこの値が指定されたものとみなされる。

limit に -1 を指定した場合は制限なし(無限大)として扱う。

注意

サーバ側のコンフィグレーションによっては、limit 値に制限がかけられている場合がある。この場合、上限値を越える値を指定したり -1 を指定した場合は 400 Bad Request エラーとなる。

8.3.4. 件数取得フラグ¶

条件に合致した全件数を取得したい場合は、count パラメータを 1 にセットする。これは通常、skip/limit と組み合わせて使用する。

count=1&limit=0

として検索した場合の例を以下に示す。

{
    "results":[
    ],
    "count": 539
}

limit=0 を指定しているため、results の内容は空となるが、count に件数が取得される。

8.3.5. プロジェクション¶

検索結果に含まれるオブジェクトのフィールドを制限したい場合にはprojectionにJSON形式で指定する。 projection は MongoDB と同様の書式で指定する。特定のフィールドのみを取得したい場合は以下のように指定する。

projection={"name":1}

上記を指定した場合、以下のような結果が得られる。

{
  "results":[
    {
      "_id":"52117490ac521e5637000001",
      "name":"Foo"
    }
  ],
  "currentTime": "2013-09-01T12:34:56.000Z"
}

逆に、特定のフィールドのみ抑制したい場合は以下のように指定する

projection={"name":0}

上記を指定した場合、以下のような結果が得られる。（nameのみ省略される）

{
  "results":[
    {
      "_id":"52117490ac521e5637000001",
      "score":80,
      "ACL": { /* ACL ... */ }
      "createdAt": "2013-08-27T05:19:16.000Z",
      "updatedAt": "2013-08-27T05:19:16.000Z",
      "etag": "8c92c97e-01a7-11e4-9598-53792c688d1b"
    }
  ],
  "currentTime": "2013-09-01T12:34:56.000Z"
}

"_id"フィールドはデフォルトで付加されるが、省きたい場合は以下のように指定する。

projection={"name":1, "_id":0}

上記を指定した場合、以下のような結果が得られる。

{
  "results":[
    {"name":"Foo"}
  ],
  "currentTime": "2013-09-01T12:34:56.000Z"
}

入れ子構造になっているフィールドを指定する場合は以下のようにする。

projection={"parent.child":1}

上記を指定した場合、以下のような結果が得られる。

{
  "results":[
    {
      "_id":"52117490ac521e5637000001",
      "parent": {"child": 123}
    }
  ],
  "currentTime": "2013-09-01T12:34:56.000Z"
}

フィールドは複数指定する事が可能だが、"0"と"1"を混在させることはできない。但し、「"_id":0」のみ例外的に併用可能。

正しい例:

projection={"name":1, "age":1}
projection={"name":0, "age":0}
projection={"name":1, "age":1, "_id":0}

正しくない例

projection={"name":1, "age":0}
projection={"name":0, "age":0, "_id":1}

また、arrayフィールドに対して、MongoDBと同様に以下の演算子を使用することも可能。

$elemMatch
$slice

【注意】 "$", "$meta" 演算子は対象外。

8.3.6. readPreference¶

使用するMongoDBがレプリカセットで構築されている場合のみ有効なパラメータ。

参照するDBを以下の値で指定できる。（大文字小文字は区別されない）指定しない場合はデフォルトでprimaryとなる。

primary: プライマリから読み込む（デフォルト）
secondaryPreferred: セカンダリ優先で読み込む。セカンダリが複数ある場合はランダムに選択される。セカンダリが存在しない場合はプライマリから読み込む。

これ以外の値を指定した場合はBadRequestとなる。

注意

セカンダリから読む場合、古い情報が得られる場合がある。これは、プライマリからセカンダリへの複製処理で若干の遅延が発生するため。最新状態を取得する必要がある場合はセカンダリを指定しないこと。