REST API APPENDIX (REST API)
最終更新日 2015-9-28

データ検索における条件式

データ検索をおこなうための条件式について

「REST API » JSON オブジェクト API » JSON オブジェクトを検索する」 に説明されるように、
JSON オブジェクトを検索するときに「オブジェクト ID」を指定する代わりに matrix パラメータ形式の条件式を指定することで
コレクションに含まれる複数のオブジェクトの条件検索を行うことができます。

既にご利用いただいているお客様へ

API 「JSON オブジェクト検索」における 注意事項の記事を追加 しました。
重要な内容が含まれますので、ぜひご一読いただきますようお願いいたします。
    »»»「OR の内部で AND を指定できません」

条件式の基本

JSON データ検索のエンドポイントに対し、matrix パラメータ形式の条件式のクエリを、以下のように指定することができます。

/v1/dat/{データストアID}/{アプリID}/{コレクションID}/{取得開始位置}-{取得終了位置};{検索条件1};{検索条件2};{検索条件3};…?{クエリパラメータ}

エンドポイントにクエリ指定できる条件式について、その基本的なルールを説明します。

  • {取得開始位置} や {取得終了位置} の数値は省略できますが、間にある “-” (ハイフン) は省略できません

  • 条件式の値は文字列として扱われます
    /v1/dat/montreal/cafe/members/-;sex.eq.female;
    結果 :
        (女性)
        ・・・・「女性」

  • 文字列以外の型を扱いたい場合、値の末尾に “n” をつけてください
    /v1/dat/montreal/cafe/members/-;age.gte.18n
    結果 :
        (18 才以上)
        ・・・・「18 才以上」

  • AND 検索をおこなう場合、複数の条件を “;” で繋ぎます
    (条件式の最後に “;” をつけることが奨励されます)
    /v1/dat/montreal/cafe/members/-;age.gte.18n;sex.eq.female;
    結果 :
        (18 才以上) AND (女性)
        ・・・・「18 才以上の女性」

  • OR 検索をおこなう場合、複数の条件を “or{}” で繋ぎます。
    /v1/dat/montreal/cafe/members/-;age.gte.18n;sex.eq.female;or{married.is.true};
    結果 :
        (18 才以上) AND (女性) OR (既婚)
        ・・・・「18 才以上の女性」または「既婚」

  • “or{}” の内部の “;” は OR として認識されます
    /v1/dat/montreal/cafe/members/-;age.gte.18n;sex.eq.female;or{married.is.true;kids.is.true};
    (詳細な 注意事項が記載 された 「OR の内部で AND を指定できません」 を参照ください)
    結果 :
        (18 才以上) AND (女性) OR (既婚) OR (子連れ)
        ・・・・「18 才以上の女性」または「既婚」または「子連れ」

  • “or{}” の外にある条件は AND として連結されます
    /v1/dat/montreal/cafe/members/-;age.gte.18n;sex.eq.female;or{married.is.true;kids.is.true};favorite.in.cooking;
    結果 :
        (18 才以上) AND (女性) OR (既婚) OR (子連れ) AND (料理が好き)
        ・・・・「18 才以上で料理が好きな女性」または「既婚」または「子連れ」

  • ネストされたデータのフィールドを検索したい場合、それぞれの階層を “.” で繋げて指定します
    例えば zoo というコレクションに
    {
        “animal”: {
            “cat”: “meow”
        }
    }

    というデータがある場合
    zoo/-;animal.cat.eq.meow;
    のように検索します。

  • “}” を検索するとき、AND 条件の中では正常に検索できますが、OR 条件の中では正常に検索できません
    例えば
    {
        “key”: “}}}}
    }

    というデータがあった場合、これを検索するために
    key.li.}
    のように “}” を LIKE 検索することはできますが
    or{key.li.};}
    のように全体を “or{}” で囲むと、検索対象であったはずの “}” は “or{}” を区切るためのそれであると認識され、検索に失敗します。

  • 地理情報の検索をする場合、条件式に指定する座標については、(1) 経度、(2) 緯度 の順で指定してください
    例えば restaurants というコレクションに
    緯度: 37.79232
    経度: -122.399933
    つまり
    {
        _coord: {
            -122.399933,
            37.79232
        }
    }

    という座標をふくむデータがあるとき、これを条件式に表現する場合は
    restaurants/-;_coord.wic.37.79232,-122.399933,4; ← 緯度, 経度
    ではなく、
    restaurants/-;_coord.wic.-122.399933,37.79232,4; ← 経度, 緯度
    のように指定します。

  • “or{}” の内部で組み合わせた複数の条件に、地理情報の検索条件が含まれていた場合、検索することはできません
    例えば
    restaurants/-;_coord.wic.xxx,xx,4;food.eq.good;
    は検索できますが
    restaurants/-;or{_coord.wic.xxx,xx,4;food.eq.good};
    は検索できません。
    (注意) 上記の例で座標を xxx,xx と表現しているのは便宜的なものであることをご留意ください(以下、同様)

  • 地理情報の検索について「wic と wic の組み合わせ」による AND 検索はできますが、
    いずれかが “or{}” の内部にある場合、もしくはどちらも “or{}” の内部にある場合は、検索できません

    例えば
    restaurants/-;_coord.wic.xxx,xx,10;_coord.wic.xxx,xx,10;
    は検索できますが
    restaurants/-;or{_coord.wic.xxx,xx,10};_coord.wic.xxx,xx,10;
    または
    restaurants/-;or{_coord.wic.xxx,xx,10;_coord.wic.xxx,xx,10};
    のように “or{}” が用いられていると検索できません。

  • 地理情報の検索について「wic と wip の組み合わせ」による AND/OR 検索できますが、「wic と wib の組み合わせ」による AND/OR 検索はできません
    /-;_coord.wic.xxx,xx,10;_coord.wip.xxx,xx,xxx,xx,xxx,xx;
    は検索できますが
    /-;_coord.wic.xxx,xx,10;_coord.wib.xxx,xx,xxx,xx;
    は検索できません。

  • 以下の文字は検索できません
    \ / % ? ; = #
    またこれ以外にも、いくつかの特殊文字 (Д ♪ ㍗ その他) は利用できません。

条件式仕様

matrix パラメータ形式で指定可能なクエリ条件式の仕様は以下のとおりです。

演算子 演算子の意味 書式 条件 備考
exist exist <フィールド名>.exist.<値> 1 : フィールドが存在する
0 : フィールドが存在しない
eq equal <フィールド名>.eq.<値> フィールド値が<値>
neq not equal <フィールド名>.neq.<値> フィールド値が<値>ではない フィールドが存在しないものも含まれる
is is <フィールド名>.is.null フィールド値がnull
<フィールド名>.is.true フィールド値がtrue
<フィールド名>.is.false フィールド値がfalse
isn is not <フィールド名>.isn.null フィールド値がnullではない
<フィールド名>.isn.true フィールド値がtrueではない
<フィールド名>.isn.false フィールド値がfalseではない
lt less than <フィールド名>.lt.<値> フィールド値が<値>より小さい
lte less than equal <フィールド名>.lte.<値> フィールド値が<値>以下
gt greater than <フィールド名>.gt.<値> フィールド値が<値>より大きい
gte greater than equal <フィールド名>.gte.<値> フィールド値が<値>以上
sw starts with <フィールド名>.sw.<値> フィールド値が<値>から始まる 大文字・小文字を判別する
swi starts with option i <フィールド名>.swi.<値> フィールド値が<値>から始まる 大文字・小文字を判別しない
nsw not start with <フィールド名>.nsw.<値> フィールド値が<値>から始まらない 大文字・小文字を判別する
nswi not start with option i <フィールド名>.nswi.<値> フィールド値が<値>から始まらない 大文字・小文字を判別しない
ew ends with <フィールド名>.ew.<値> フィールド値が<値>で終わる 大文字・小文字を判別する
ewi ends with option i <フィールド名>.ewi.<値> フィールド値が<値>で終わる 大文字・小文字を判別しない
new not end with <フィールド名>.new.<値> フィールド値が<値>で終わらない 大文字・小文字を判別する
newi not end with option i <フィールド名>.newi.<値> フィールド値が<値>で終わらない 大文字・小文字を判別しない
li like <フィールド名>.li.<値> フィールド値が<値>を含む 大文字・小文字を判別する
lii like option i <フィールド名>.lii.<値> フィールド値が<値>を含む 大文字・小文字を判別しない
in in <フィールド名>.in.<値1>,…,<値n> フィールド値が<値1>,…,<値n>のいずれか
wic within circle _coord.wic.<経度>,<緯度>,<半径> 中心座標から<半径>kmの円に収まるもの
wib within box _coord.wib.<経度1>,<緯度1>,<経度2>,<緯度2> 座標1と座標2を角とする傾いていない矩形に収まるもの
_coord.wib.<経度1>,<緯度1>,<経度2>,<緯度2>,rc,<基準座標経度>,<基準座標緯度> 座標1と座標2を角とする傾いていない矩形に収まっており、基準座標から近い順 rcが指定される場合はレスポンスに基準座標からの距離(メートル)をdistanceとして返します
wip within polygon _coord.wip.<経度1>,<緯度1>,・・・,<経度n>,<緯度n> 座標1,・・・,座標n,座標1を結んだポリゴンに収まるもの
_coord.wip.<経度1>,<緯度1>,・・・,<経度n>,<緯度n>,rc,<基準座標経度>,<基準座標緯度> 座標1,・・・,座標n,座標1を結んだポリゴンに収まっており、基準座標から近い順