2019-10-05 17:58:59 +02:00
# Parameters
2020-05-25 18:11:45 +02:00
See the [parameters' concepts ](../concepts/parameters.md ) for details.
2019-10-05 17:58:59 +02:00
::: warning
2020-05-25 18:11:45 +02:00
By default, the filters can only be used from `find` and `count` endpoints generated by the Content Type Builder and the [CLI ](../cli/CLI.md ). If you need to implement a filter system somewhere else, read the [programmatic usage ](../concepts/parameters.md ) section.
2019-10-05 17:58:59 +02:00
:::
## Available operators
The available operators are separated in four different categories:
- [Filters ](#filters )
- [Sort ](#sort )
- [Limit ](#limit )
- [Start ](#start )
## Filters
Filters are used as a suffix of a field name:
2020-02-02 16:04:22 +01:00
- No suffix or `eq` : Equals
2019-10-05 17:58:59 +02:00
- `ne` : Not equals
2020-02-02 16:04:22 +01:00
- `lt` : Less than
2019-10-05 17:58:59 +02:00
- `gt` : Greater than
2020-02-02 16:04:22 +01:00
- `lte` : Less than or equal to
2019-10-05 17:58:59 +02:00
- `gte` : Greater than or equal to
- `in` : Included in an array of values
- `nin` : Isn't included in an array of values
- `contains` : Contains
- `ncontains` : Doesn't contain
- `containss` : Contains case sensitive
- `ncontainss` : Doesn't contain case sensitive
- `null` : Is null/Is not null
### Examples
#### Find users having `John` as first name.
`GET /users?firstName=John`
or
`GET /users?firstName_eq=John`
#### Find restaurants having a price equal or greater than `3`.
`GET /restaurants?price_gte=3`
2020-02-02 16:04:22 +01:00
#### Find multiple restaurant with id 3, 6, 8.
2019-10-05 17:58:59 +02:00
`GET /restaurants?id_in=3&id_in=6&id_in=8`
#### Or clauses
If you use the same operator (except for in and nin) the values will be used to build an `OR` query
`GET /restaurants?name_contains=pizza&name_contains=giovanni`
2019-11-22 15:03:20 +01:00
::: warning
2020-02-02 16:04:22 +01:00
If you want to use `AND` for your query you will have to create a custom query by using the [Query ](../concepts/queries.md ) documentation.
2019-11-22 15:03:20 +01:00
2020-07-16 09:13:36 +00:00
Strapi doesn't support the `AND` operator for now.
2019-11-22 15:03:20 +01:00
:::
2019-10-05 17:58:59 +02:00
## Deep filtering
Find restaurants owned by a chef who belongs to a restaurant with star equal to 5
2020-02-02 16:04:22 +01:00
`GET /restaurants?chef.restaurant.star=5`
2019-10-05 17:58:59 +02:00
::: warning
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 your query.
:::
2019-11-07 12:05:39 +01:00
::: tip
2020-02-02 16:04:22 +01:00
This feature doesn't allow you to filter nested models, e.g. `Find users and only return their posts older than yesterday` .
2019-10-05 17:58:59 +02:00
2020-02-02 16:04:22 +01:00
To achieve this, there are three options:
2019-10-05 17:58:59 +02:00
2020-02-02 16:04:22 +01:00
- Build a custom route.
- Modify your services.
- Use [GraphQL ](../plugins/graphql.md#query-api ).
2019-10-05 17:58:59 +02:00
:::
::: warning
This feature isn't available for the `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`
2019-11-18 05:26:51 +00:00
#### Sorting on multiple fields
2019-10-05 17:58:59 +02:00
- `GET /users?_sort=email:asc,dateField:desc`
- `GET /users?_sort=email:DESC,username:ASC`
## Limit
Limit the size of the returned results.
2020-04-01 11:48:38 +02:00
The default limit is `100`
2019-10-05 17:58:59 +02:00
### Example
#### Limit the result length to 30.
`GET /users?_limit=30`
2020-02-02 16:04:22 +01:00
You can require the full data set by passing a limit equal to `-1` .
2019-10-05 17:58:59 +02:00
## Start
Skip a specific number of entries (especially useful for pagination).
### Example
#### Get the second page of results.
`GET /users?_start=10&_limit=10`