メインコンテンツまでスキップ

REST API: フィルター

REST API では、「ドキュメント一覧を取得」 の結果にフィルターをかけられます。
オプション機能を使うと、次のようなフィルターも利用できます。

Tip

Strapi takes advantage of the ability of the `qs` library to parse nested objects to create more complex queries.

Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.

You can also use the interactive query builder if you prefer playing with our online tool instead of generating queries with qs on your machine.

クエリでは次の構文で filters パラメータを渡せます。

GET /api/:pluralApiId?filters[field][operator]=value

利用できるオペレータは次のとおりです。

オペレータ説明
$eq等しい
$eqi等しい（大文字小文字を区別しない）
$ne等しくない
$nei等しくない（大文字小文字を区別しない）
$lt未満
$lte以下
$gtより大きい
$gte以上
$in配列に含まれる
$notIn配列に含まれない
$contains含む
$notContains含まない
$containsi含む（大文字小文字を区別しない）
$notContainsi含まない（大文字小文字を区別しない）
$nullnull である
$notNullnull でない
$between範囲内である
$startsWith前方一致
$startsWithi前方一致（大文字小文字を区別しない）
$endsWith後方一致
$endsWithi後方一致（大文字小文字を区別しない）
$orフィルターを OR で結合
$andフィルターを AND で結合
$notフィルターを NOT で結合

filters オブジェクトに複数フィールドを渡すと、暗黙的に $and で結合されます（例: GET /api/restaurants?filters[stars][$gte]=3&filters[open][$eq]=true は、営業中かつ星 3 以上のレストランのみ返します）。

Tip

$and、$or、$not は相互にネストできます。

Caution

既定では、フィルターは Content-Type Builder と CLI が生成する find エンドポイントからのみ使えます。

例: 名（ファーストネーム）が「John」のユーザーを検索​

完全一致には $eq を使います。


名が「John」のユーザーを検索

GET /api/users?filters[username][$eq]=John

JavaScript のクエリ（qs ライブラリで組み立て）:

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  filters: {
    username: {
      $eq: 'John',
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/users?${query}`);
レスポンス例
{
  "data": [
    {
      "id": 1,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "username": "John",
      "email": "john@test.com",
      "provider": "local",
      "confirmed": true,
      "blocked": false,
      "createdAt": "2021-12-03T20:08:17.740Z",
      "updatedAt": "2021-12-03T20:08:17.740Z"
    }
  ],
  "meta": {
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 1,
    "total": 1
  }
}

例: id が 3、6、8 のレストランを複数取得​

配列の値と $in で、複数の完全一致を検索できます。


id が 3、6、8 のレストランを検索

GET /api/restaurants?filters[id][$in][0]=3&filters[id][$in][1]=6&filters[id][$in][2]=8

JavaScript のクエリ（qs ライブラリで組み立て）:

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  filters: {
    id: {
      $in: [3, 6, 8],
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);
レスポンス例
{
  "data": [
    {
      "id": 3,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test3",
      // ...
    },
    {
      "id": 6,
      "documentId": "ethwxjxtvuxl89jq720e38uk",
      "name": "test6",
      // ...
    },
    {
      "id": 8,
      "documentId": "cf07g1dbusqr8mzmlbqvlegx",
      "name": "test8",
      // ...
    },
  ],
  "meta": {
    // ...
  }
}

複合フィルター​

複合フィルターでは、$and と $or などを組み合わせて、必要なデータだけを柔軟に取得します。


日付の候補が 2 通りかつ著者名が特定の本を検索

GET /api/books?filters[$and][0][$or][0][date][$eq]=2020-01-01&filters[$and][0][$or][1][date][$eq]=2020-01-02&filters[$and][1][author][name][$eq]=Kai%20doe

JavaScript のクエリ（qs ライブラリで組み立て）:

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  filters: {
    $and: [
      {
        $or: [
          {
            date: {
              $eq: '2020-01-01',
            },
          },
          {
            date: {
              $eq: '2020-01-02',
            },
          },
        ],
      },
      {
        author: {
          name: {
            $eq: 'Kai doe',
          },
        },
      },
    ],
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/books?${query}`);
レスポンス例
{
  "data": [
    {
      "id": 1,
      "documentId": "rxngxzclq0zdaqtvz67hj38d",
      "name": "test1",
      "date": "2020-01-01",
      // ...
    },
    {
      "id": 2,
      "documentId": "kjkhff4e269a50b4vi16stst",
      "name": "test2",
      "date": "2020-01-02",
      // ...
    }
  ],
  "meta": {
    // ...
  }
}

ディープフィルター​

ディープフィルターは、リレーション先のフィールドで絞り込む方法です。

Note
  • リレーション、メディア、コンポーネント、ダイナミックゾーンは既定ではポピュレートされません。populate で構造を含めます（populate のドキュメント 参照）。
  • ポピュレートした内容にフィルターをかけたり、ネストしたリレーションにフィルターをかけたりはできますが、メディアやダイナミックゾーンなど多態的な構造にフィルターは使えません。
Caution

ディープフィルター付きの API クエリはパフォーマンスに影響することがあります。遅いクエリがある場合は、最適化したクエリを使うカスタムルートの実装を検討してください。

Deep filtering with the various APIs

For examples of how to deep filter with the various APIs, please refer to this blog article.

5 つ星レストランに所属するシェフがオーナーのレストランを検索

GET /api/restaurants?filters[chef][restaurants][stars][$eq]=5

JavaScript のクエリ（qs ライブラリで組み立て）:

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  filters: {
    chef: {
      restaurants: {
        stars: {
          $eq: 5,
        },
      },
    },
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);
レスポンス例
{
  "data": [
    {
      "id": 1,
      "documentId": "cvsz61qg33rtyv1qljb1nrtg",
      "name": "GORDON RAMSAY STEAK",
      "stars": 5
      // ...
    },
    {
      "id": 2,
      "documentId": "uh17h7ibw0g8thit6ivi71d8",
      "name": "GORDON RAMSAY BURGER",
      "stars": 5
      // ...
    }
  ],
  "meta": {
    // ...
  }
}
このページを編集