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

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

このサイトを正しく表示するためには、ブラウザーのJavaScriptの設定を「有効」にしてください。

REST API リファレンス

共通ドキュメント

クエリの指定方法

1 このページについて
2 標準クラスを検索する場合のクラス名
3 より効率的に検索するには
4 使用可能なオペレータ
5 更新で使用可能なオペレータ
6 クエリの作成例

このページについて

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://mbaas.api.nifcloud.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	ユニーク
端末管理(installation)	deviceToken	ユニーク
プッシュ(push)	objectId	ユニーク
	deliveryTime
	status
	deliveryTime, status	複合
	status, deliveryTime	複合
ファイル(file)	objectId	ユニーク
ファイル(file)	fileName	ユニーク

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

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

使用可能なオペレータ

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

※フィールドを暗号化している場合、使用できないオペレータがございます。詳しくはデータストア：基本的な使い方＃暗号化の設定（iOS）をご覧ください。

項目の検索

機能	オペレータ
等しい	なし
等しくない	$ne
より小さい	$lt
より大きい	$gt
以下	$lte
以上	$gte
いずれかが含まれる	$in
いずれも含まれない	$nin
フィールドが存在する	$exists
正規表現での比較 ※文字列のみ	$regex

※「$in」、「$nin」使用時には、条件の配列の要素数にご注意ください。詳しくは開発ガイドラインの「検索クエリについて」をご参考ください。

配列の検索

機能	オペレータ
いずれかが含まれる	$inArray
いずれも含まれない	$ninArray
すべて含まれる	$all

※「$inArray」、「$ninArray」使用時には、条件の配列の要素数にご注意ください。詳しくは開発ガイドラインの「検索クエリについて」をご参考ください。

複合条件検索

機能	オペレータ
すべてを満たす	なし
いずれかを満たす	$or
サブクエリと合致するデータのうち、クエリとサブクエリで指定したキーの値が一致するデータを取得	$select

※「$or」に空配列を指定することはできません。指定した場合はエラーが返却されます。
※同一フィールドでの複合条件検索には「$or」を利用しないでください。詳しくは開発ガイドラインの「検索クエリについて」をご参考ください。

ポインタの検索（リレーションも含む）

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

※「$relatedTo」使用時に「skip」・「limit」を指定した場合は「$relatedTo」で指定した親のRelationデータに対して適用されます。なお「order」・「count」は子のデータに対して適用されます。「$relatedTo」使用時の注意事項については、開発ガイドラインの「リレーションについて」に詳細を記載していますので、あわせてご参考ください。

位置情報検索

機能	オペレータ
指定位置から距離が近い順でデータを取得 (orderを指定した場合は、orderが優先される) オプションで最遠距離を以下の単位で指定可能 $maxDistanceInMiles → マイル $maxDistanceInKilometers → キロメートル $maxDistanceInRadians → ラジアン	$nearSphere
指定矩形の内側に存在するデータを取得矩形は$boxを使って左下、右上を指定	$within / $box

※「$nearSphere」は緯度経度データが入っているフィールドに対してのみ使用可能です。緯度経度データが入っていない場合エラーとなります。

その他クエリのキーについて

機能	キーの名前
子の情報も含めて親情報を取得 (ポインタのみ、Relationは不可)	include
並び順を指定する (降順はマイナス付与) カンマで区切ると複数項目の並べ替えが可能	order
開始位置を指定する	skip
件数を取得する	count
取得件数を指定する（デフォルトは100、有効値は1～1000）	limit

※ limitを指定していない場合、デフォルトが100件となり、検索結果として取得される最大データ件数は100件です。検索結果のデータ件数が多い場合は、limitとskipを活用してください。
※ 副問い合わせ「$select」・「$inQuery」について、副問い合わせに対して「order」・「skip」・「limit」の指定が可能。指定する場合は副問い合わせ内の「where」キーと同列で指定を行います。
※ 「$relatedTo」使用時には、「count」は全データ件数ではなく取得したデータ件数を返却します。また、「order」についても「$relatedTo」使用時には全データを並び替えるのではなく、取得してきたデータのみを並び替えします。

更新で使用可能なオペレータ

上に書いたオペレータ以外にも、更新時にのみ使用可能なオペレータが以下のように存在しています。
更新オペレーションを使用することで、オブジェクト全体を上書きすることなく、指定の値を更新できます。
※これらのオペレーション設定後にupdateを実行する必要があります。

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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.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://mbaas.api.nifcloud.com/2013-09-01/classes/testClass

特定のエラーが発生していたプッシュ通知を取得する

iOS端末でunregisteredエラーが発生していたプッシュ通知を検索する

curl -X GET -G \
 -H "X-NCMB-Application-Key: 5b30da7832236ac49f6a61493dd601e07c31327cf2cd454da77df59439f69938" \
 -H "X-NCMB-Timestamp: 2023-01-26T07:20:24.677Z" \
 -H "X-NCMB-Signature: mDQxzCBOC1blmYGRuJg0YCjPGlArQTbsb6RVKN1b7s0=" \
 -H "Content-Type: application/json" \
 --data-urlencode 'where={"error.ios.unregistered":{"$exists": true}}' \
https://mbaas.api.nifcloud.com/2013-09-01/push

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

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

ページの先頭へ