Filters

See the filters' concepts for details.

By default, the filters can only be used from find endpoints generated by the Content Type Builder and the CLI. If you need to implement a filters system somewhere else, read the programmatic usage section.

Available operators

The available operators are separated in four different categories:

Filters

Easily filter results according to fields values.

  • =: Equals
  • _ne: Not equals
  • _lt: Lower than
  • _gt: Greater than
  • _lte: Lower than or equal to
  • _gte: Greater than or equal to
  • _in: Include in array
  • _contains: Contains
  • _containss: Contains case sensitive
  • _in: Matches any value in the array of values
  • _nin: Doesn't match any value in the array of values

Examples

Find users having John as first name.

GET /users?firstName=John

Find products having a price equal or greater than 3.

GET /products?price_gte=3

Find multiple product with id 3, 6, 8 GET /products?id_in=3&id_in=6&id_in=8

You can't use filter to have specific results inside relation, like "Find users and only their posts older than yesterday" as example. If you need it, you can modify or create your own service or use GraphQL.

WARNING

This filter isn't available for upload plugin.

Sort

Sort according to a specific field.

Example

Sort users by email.

  • ASC: GET /users?_sort=email:ASC
  • DESC: GET /users?_sort=email:DESC

Limit

Limit the size of the returned results.

Example

Limit the result length to 30.

GET /users?_limit=30

Start

Skip a specific number of entries (especially useful for pagination).

Example

Get the second page of results.

GET /users?_start=10&_limit=10

Programmatic usage

Requests system can be implemented in custom code sections.

Extracting requests filters

To extract the filters from a JavaScript object or a request, you need to call the strapi.utils.models.convertParams helper.

The returned objects are formatted according to the ORM used by the model.

Example

Path — ./api/user/controllers/User.js.

// Define a list of params.
const params = {
  '_limit': 20,
  '_sort': 'email'
};

// Convert params.
const formattedParams = strapi.utils.models.convertParams('user', params); // { limit: 20, sort: 'email' }

Query usage

Example

Path — ./api/user/controllers/User.js.

module.exports = {

  find: async (ctx) => {
    // Convert params.
    const formattedParams = strapi.utils.models.convertParams('user', ctx.request.query);

    // Get the list of users according to the request query.
    const filteredUsers = await User
      .find()
      .where(formattedParams.where)
      .sort(formattedParams.sort)
      .skip(formattedParams.start)
      .limit(formattedParams.limit);

    // Finally, send the results to the client.
    ctx.body = filteredUsers;
  };
};