サーバー構築不要!スマートフォンアプリ向けの新クラウド

トップ >ドキュメント >REST API リファレンス:クエリの指定方法

共通ドキュメント

クエリの指定方法

このページについて

APIをリクエストする場合のクエリ指定について説明します。

APIリクエスト時にクエリを指定する場合は、JSONパラメータをURLエンコードする必要があります。
以下は、オブジェクト検索時のcurlサンプルですが、--data-urlencodeでクエリを指定しています。

curl -X GET -G \
 -H "X-NCMB-Application-Key:549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp:2013-09-10T02:44:35.452Z" \
 -H "X-NCMB-Signature: bqPSP/7iXvjDRhrsSX9zasAfvgqvyeAKMJIU3/yLaX4=" \
 -H "Content-Type: application/json" \
 --data-urlencode 'where={"name":"curl"}'\
 https://mb.api.cloud.nifty.com/2013-09-01/classes/cmd

標準クラスを検索する場合のクラス名

会員やロール・ファイルなど、mobile backendに標準で存在するクラスに対して、
inQueryを用いた検索など、クラス名を指定する必要がある場合は以下をご覧ください。

クラス名 役割
user 会員管理のクラス
role ロールのクラス
file ファイルストアのクラス
installation 端末情報一覧のクラス
push プッシュ通知のクラス

より効率的に検索するには

データストアで頻繁に実施される検索・取得処理やソート処理がある場合、
データストアの検索対象となるフィールドに対してインデックスを追加しておくと、
処理が効率化され、レスポンスタイムを早くすることができます。

各クラスにはシステム側でインデックス追加済みのフィールドがあります。
より効率良く検索を実施したい場合は、
こちらのフィールドを活用した検索条件の指定を推奨しています。

対象リソース フィールド 補足
データストア(classes) objectId ユニーク
会員管理(user) objectId ユニーク
userName ユニーク
mailAddress
sessionInfo.sessionToken ユニーク
ロール(role) objectId ユニーク
roleName ユニーク
belongUser.objectId
belongRole.objectId
端末管理(installation) objectId ユニーク
deviceToken ユニーク
プッシュ(push) objectId ユニーク
deliveryTime
status
deliveryTime, status 複合
status, deliveryTime 複合
ファイル(file) objectId ユニーク
fileName ユニーク

※注意
 ユニーク:そのフィールドに登録される値が一意になるような制約が付いたインデックス
 複合  :複数フィールドに対するインデックス

その他のフィールドにもインデックスを追加することは可能です(有料)。
インデックス機能の詳細についてはこちらでご覧ください。

使用可能なオペランド

whereキーのクエリで利用可能なオペランドは、以下のとおりです。
オペランドは組み合わせて使用することで、複雑な検索を行うことができます。

項目の検索
機能 オペランド
等しい なし
等しくない $ne
より小さい $lt
より大きい $gt
以下 $lte
以上 $gte
いずれかが含まれる $in
いずれも含まれない $nin
フィールドが存在する $exists
正規表現での比較 ※文字列のみ $regex
配列の検索
機能 オペランド
いずれかが含まれる $inArray
いずれも含まれない $ninArray
すべて含まれる $all
複合条件検索
機能 オペランド
すべてを満たす なし
いずれかを満たす $or
サブクエリと合致するデータのうち、クエリとサブクエリで指定したキーの値が一致するデータを取得 $select

※注意
 $orに空配列を指定することはできません。指定した場合はエラーが返却されます。

ポインタの検索(リレーションも含む)
機能 オペランド
等しい(1項目) なし
サブクエリに合致するデータを、ポインタとして持っているデータを取得 $inQuery
オブジェクトIDが指定された親のリレーションにひもづく子のデータを取得 $relatedTo

※「$relatedTo」使用時に「skip」・「limit」を指定した場合は「$relatedTo」で指定した親のRelationデータに対して適用されます。なお「order」は子のデータに対して適用されます。

位置情報検索
機能 オペランド
指定位置から距離が近い順でデータを取得
(orderを指定した場合は、orderが優先される)
オプションで最遠距離を以下の単位で指定可能
$maxDistanceInMiles → マイル
$maxDistanceInKilometers → キロメートル
$maxDistanceInRadians → ラジアン
$nearSphere
指定矩形の内側に存在するデータを取得
矩形は$boxを使って左下、右上を指定
$within / $box
その他クエリのキーについて
機能 キーの名前
子の情報も含めて親情報を取得
(ポインタのみ、Relationは不可)
include
並び順を指定する
(降順はマイナス付与)
カンマで区切ると複数項目の並べ替えが可能
order
開始位置を指定する skip
件数を取得する count
取得件数を指定する
(デフォルトは100、有効値は1~1000)
limit

※副問い合わせ「$select」・「$inQuery」について、副問い合わせに対して「order」・「skip」・「limit」の指定が可能。指定する場合は副問い合わせ内の「where」キーと同列で指定を行います。

更新で利用可能なオペランド

上に書いたオペランド以外にも利用可能なオペランドが以下のように存在しています。

Increment

ある数値フィールドに対してインクリメント・デクリメントを行います。

{"score":{"__op":"Increment","amount":1}}

Add

配列の末尾にオブジェクトを追加します。

{"food":{"__op":"Add","objects":["vegetable"]}}

AddUnique

重複したデータを避けて配列に追加します。このとき、挿入位置は保証されません。

{"skills":{"__op":"AddUnique","objects":["flying","kungfu"]}}

Remove

配列フィールドから指定された値を削除する

{"food":{"__op":"Remove","objects":["meat"]}}

AddRelation

既存のオブジェクトに別オブジェクトを参照するポインタを関連付けます。
※追加するオブジェクトは既存のデータのみ可能です。
※複数クラスのオブジェクトは追加できません。

{"opponents":{"__op":"AddRelation","objects":[{"__type":"Pointer","className":"Player","objectId":"Vx4nudeWn"}]}}

RemoveRelation

リレーション内のオブジェクトを削除します。

{"opponents":{"__op":"RemoveRelation","objects":[{"__type":"Pointer","className":"Player","objectId":"Vx4nudeWn"}]}}

クエリの作成例

スコアが1000以上かつ3000以下を取得する
curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"score":{"$gte":1000,"$lte":3000}}' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/GameScore

配列(arrayKey)の値が2,3,4すべてと一致するデータを取得する
curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"arrayKey":{"$all":[2,3,4]}}' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/GameScore

or検索でデータを取得する

日付と文字列のデータを$orの条件に指定して検索

curl -X GET -G \
 -H "X-NCMB-Application-Key:b8cfe143fb5e9fb54af2456af6427f05d9a7615f976a7fc1f140db251290941c" \
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z" \
 -H "X-NCMB-Signature: 5mtjcVuMq5FMTlgJDzuyo2ONWw6SA4WTdiTjuD0KiJw=" \
 -H "Content-Type: application/json" \
 --data-urlencode 'where={"$or":[{"createDate":{"__type":"Date", "iso":"2014-03-06T07:09:11.856Z"}},{"str":"data1"}]}'  \
 https://mb.api.cloud.nifty.com/2013-09-01/classes/queryTestClass

比較の集合を利用した検索のサンプル

Teamクラスの勝率(winPct)が5割超えの都市(city)をホーム(hometown)に持つTownクラスのデータをスコアの昇順で取得する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"hometown":{"$select":{"query":{"className":"Team","where":{"winPct":{"$gte":0.5}}},"key":"city"}}}&order=score' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/Town

日付型での検索サンプル

1994年2月18日の12時以降のデータを検索する
(下記のリクエストサンプルではUTCの3時と設定しているため、JSTで12時になります)
(mobile backendでの日付型はUTCでの指定のみ可能です)

curl -X GET -G \
 -H "X-NCMB-Application-Key:4911b6ff9b30311c0e47f7bb9f132b67ba10c3a187d64c33f98882394a5cca34" \
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z" \
 -H "X-NCMB-Signature: BW78owFbkyiqfFyUdy3lwfonm2b5RheVq3hG9N66mOU=" \
 -H "Content-Type: application/json" \
 --data-urlencode 'where={"date":{"$gte":{"__type":"Date","iso":"1994-02-18T03:00:00.000Z"}}}' \
 https://mb.api.cloud.nifty.com/2013-09-01/classes/queryTestClass

結果

{
    "results": [
        {
            "objectId": "Zvp2UJYwD3e9qGid",
            "createDate": "2014-04-24T08:32:56.954Z",
            "updateDate": "2014-04-24T08:32:57.186Z",
            "acl": {
                "*": {
                    "read": true,
                    "write": true
                }
            },
            "int": 50,
            "place": {
                "__type": "GeoPoint",
                "longitude": 50,
                "latitude": 50
            },
            "obj": {
                "key": "data5"
            },
            "str": "data5",
            "array": [
                "arry9",
                "arry10"
            ],
            "date": {
                "__type": "Date",
                "iso": "1994-02-18T04:00:00.000Z"
            },
            "bool": true
        }
    ]
}

ポインタのサンプル

Commentクラスのpostフィールドの値が、Postクラスの特定のオブジェクトId(8TOXdXf3tz)と紐付いているCommentクラスのデータを取得する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"post":{"__type":"Pointer","className":"Post","objectId":"8TOXdXf3tz"}}' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/Comment

サブクエリを利用したサンプル

Postクラスにimageが存在するサブクエリと、Commentのpostの値と合致する、データを取得する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"post":{"$inQuery":{"where":{"image":{"$exists":true}},"className":"Post"}}}' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/Comment

リレーション型のサンプル

PostクラスのオブジェクトID(3333)のlikesにひもづく、usersクラスのデータを取得する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'where={"$relatedTo":{"object":{"__type":"Pointer","className":"Post","objectId":"3333"},"key":"likes"}}' \
  https://mb.api.cloud.nifty.com/2013-09-01/users

リスト関連のサンプル

ポインタpostでひもづくオブジェクト、さらにそのオブジェクトが持つポインタauthorにひもづくデータも取得する

リクエストサンプル

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'include=post.author' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/Comment

レスポンスJSONサンプル

{"post":
    {"author":
        {"text":"zzzz",
         "createDate":"2013-04-11T01:49:15.313Z",
         "updateDate":"2013-04-30T09:35:38.011Z",
         "objectId":"CCC",
         "__type":"Object","className":"Test"
        },
     "createDate":"2013-04-11T08:52:40.587Z",
     "updateDate":"2013-04-30T07:27:05.237Z",
     "objectId":"000",
     "__type":"Object","className":"Post"
    },
 "createDate":"2013-04-10T10:07:48.948Z",
 "updateDate":"2013-04-30T07:21:58.482Z",
 "objectId":"aaaaa"
}

scoreが昇順、nameが降順のデータを取得する

curl -X GET -G \
-H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
-H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
-H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
-H "Content-Type: application/json" \
 --data-urlencode 'order=score,-name' \
 https://mb.api.cloud.nifty.com/2013-09-01/classes/GameScore

最初の400件をスキップした後200件のオブジェクトを取得する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 549116a86b0ebbec4832d4086a56f36c82a5d64bc6528fa5e6220be76db5ef45" \
 -H "X-NCMB-Timestamp: 2013-08-14T15:46:25.543" \
 -H "X-NCMB-Signature: 8sAdvYH5SbWvI+NIfgyBwNzlR2ZSHC99GMGsuY/uIdM=" \
 -H "Content-Type: application/json" \
  --data-urlencode 'skip=400 ' \
  --data-urlencode 'limit=200 ' \
  https://mb.api.cloud.nifty.com/2013-09-01/classes/GameScore

位置検索のサンプル

locationが、地点(lon,lat)から半径10km以内に存在するデータを近い順に取得する

curl -X GET -G -H "X-NCMB-Application-Key:b931b1b353112bb703cb7c2f92026020b04bd9329b9faf7028f8396ef5294a85"\
-H "X-NCMB-Timestamp:2013-12-08T02:44:35.452Z"\
-H "X-NCMB-Signature: MdlQ6JrFGKrH4HWmuy58t7ohP62XHm2v5Z5xRFtwyro="\
-H "Content-Type: application/json"\
--data-urlencode 'where={"location":{"$nearSphere":{"__type":"GeoPoint", "longitude":139.700432, "latitude":35.691152},"$maxDistanceInKilometers":10}}'\
https://mb.api.cloud.nifty.com/2013-09-01/classes/testClass

locationが、左下(lon,lat)~右上(lon,lat)の矩形内に存在するデータを取得する

curl -X GET -G -H "X-NCMB-Application-Key:b931b1b353112bb703cb7c2f92026020b04bd9329b9faf7028f8396ef5294a85"\
-H "X-NCMB-Timestamp:2013-12-08T02:44:35.452Z"\
-H "X-NCMB-Signature: m0qVBGDNA7IKtKajsBpdJoXJfzeKrT1HXeR/lTVrnS4="\
-H "Content-Type: application/json"\
--data-urlencode 'where={"location":{"$within":{"$box":[{"__type":"GeoPoint", "longitude":121.680432, "latitude":21.773152},\
{"__type":"GeoPoint", "longitude":150.687432, "latitude":40.773152}]}}}'\
https://mb.api.cloud.nifty.com/2013-09-01/classes/testClass

お探しの内容が見つからなかった場合はユーザーコミュニティ もご活用ください。(回答保証はいたしかねます)
なお、 Expertプラン以上のお客様はテクニカルサポートにてご質問を承らせて頂きます。

推奨画面サイズ1024×768px以上

ページの先頭へ