import QsIntroFull from '/docs/snippets/qs-intro-full.md'
import QsForQueryBody from '/docs/snippets/qs-for-query-body.md'
import QsForQueryTitle from '/docs/snippets/qs-for-query-title.md'
import DeepFilteringBlogLink from '/docs/snippets/deep-filtering-blog.md'

REST API: Filters#

The REST API offers the ability to filter results found with its "Get entries" method.

Using optional Strapi features can provide some more filters:

If the Internationalization (i18n) plugin is enabled on a content-type, it's possible to filter by locale.
If the Draft & Publish is enabled, it's possible to filter based on a published (default) or draft status.

Queries can accept a filters parameter with the following syntax:

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

The following operators are available:

Operator	Description
`$eq`	Equal
`$eqi`	Equal (case-insensitive)
`$ne`	Not equal
`$nei`	Not equal (case-insensitive)
`$lt`	Less than
`$lte`	Less than or equal to
`$gt`	Greater than
`$gte`	Greater than or equal to
`$in`	Included in an array
`$notIn`	Not included in an array
`$contains`	Contains
`$notContains`	Does not contain
`$containsi`	Contains (case-insensitive)
`$notContainsi`	Does not contain (case-insensitive)
`$null`	Is null
`$notNull`	Is not null
`$between`	Is between
`$startsWith`	Starts with
`$startsWithi`	Starts with (case-insensitive)
`$endsWith`	Ends with
`$endsWithi`	Ends with (case-insensitive)
`$or`	Joins the filters in an "or" expression
`$and`	Joins the filters in an "and" expression
`$not`	Joins the filters in an "not" expression

When several fields are passed in the filters object, they are implicitly combined with $and (e.g. GET /api/restaurants?filters[stars][$gte]=3&filters[open][$eq]=true only returns restaurants that are open and have at least 3 stars).

By default, the filters can only be used from find endpoints generated by the Content-type Builder and the CLI.

Example: Find users having 'John' as a first name#

You can use the $eq filter operator to find an exact match.

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

JavaScript query (built with the qs library):

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
  }
}

Example: Find multiple restaurants with ids 3, 6,8#

You can use the $in filter operator with an array of values to find multiple exact values.

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

JavaScript query (built with the qs library):

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": {
    // ...
  }
}

Complex filtering#

Complex filtering is combining multiple filters using advanced methods such as combining $and & $or. This allows for more flexibility to request exactly the data needed.

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 query (built with the qs library):

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": {
    // ...
  }
}

Deep filtering#

Deep filtering is filtering on a relation's fields.

Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of the query.

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

JavaScript query (built with the qs library):

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": {
    // ...
  }
}