docs/api/databases/querying.md
---
outline: deep
---
# Querying
All official database adapters support a common way for querying, sorting, limiting and selecting `find` and `get` method calls as part of `params.query`. Querying also applies `update`, `patch` and `remove` method calls.
<BlockQuote label="Note">
When used via REST URLs all query values are strings and may need to be converted to the correct type. In a v5 application this is done automatically using [schemas](../schema/index.md).
</BlockQuote>
## Filters
Filters are special properties (starting with a `$`) added at the top level of a query. They can determine page settings, the properties to select and more.
### $limit
`$limit` will return only the number of results you specify:
```js
// Retrieves the first two unread messages
app.service('messages').find({
query: {
$limit: 2,
read: false
}
})
```
```
GET /messages?$limit=2&read=false
```
<BlockQuote>
With [pagination enabled](common.md#pagination), to just get the number of available records set `$limit` to `0`. This will only run a (fast) counting query against the database and return a page object with the `total` and an empty `data` array.
</BlockQuote>
### $skip
`$skip` will skip the specified number of results:
```js
// Retrieves the next two unread messages
app.service('messages').find({
query: {
$limit: 2,
$skip: 2,
read: false
}
})
```
```
GET /messages?$limit=2&$skip=2&read=false
```
### $sort
`$sort` will sort based on the object you provide. It can contain a list of properties by which to sort mapped to the order (`1` ascending, `-1` descending).
```js
// Find the 10 newest messages
app.service('messages').find({
query: {
$limit: 10,
$sort: {
createdAt: -1
}
}
})
```
```
/messages?$limit=10&$sort[createdAt]=-1
```
### $select
`$select` allows to pick which fields to include in the result. This will work for any service method.
```js
// Only return the `text` and `userId` field in a message
app.service('messages').find({
query: {
$select: ['text', 'userId']
}
})
app.service('messages').get(1, {
query: {
$select: ['text']
}
})
```
```
GET /messages?$select[]=text&$select[]=userId
GET /messages/1?$select[]=text
```
### $or
Find all records that match any of the given criteria.
```js
// Find all messages that are not marked as archived
// or any message from room 2
app.service('messages').find({
query: {
$or: [{ archived: { $ne: true } }, { roomId: 2 }]
}
})
```
```
GET /messages?$or[0][archived][$ne]=true&$or[1][roomId]=2
```
### $and
Find all records that match all of the given criteria.
```js
// Find all messages that are not marked as archived and in room 2
app.service('messages').find({
query: {
$and: [{ archived: { $ne: true } }, { roomId: 2 }]
}
})
```
```
GET /messages?$and[0][archived][$ne]=true&$and[1][roomId]=2
```
## Operators
Operators either query a property for a specific value or determine nested special properties (starting with a `$`) that allow querying the property for certain conditions. When multiple operators are set, all conditions have to apply for a property to match.
### Equality
All fields that do not contain special query parameters are compared directly for equality.
```js
// Find all unread messages in room #2
app.service('messages').find({
query: {
read: false,
roomId: 2
}
})
```
```
GET /messages?read=false&roomId=2
```
### $in, $nin
Find all records where the property does (`$in`) or does not (`$nin`) match any of the given values.
```js
// Find all messages in room 2 or 5
app.service('messages').find({
query: {
roomId: {
$in: [2, 5]
}
}
})
```
```
GET /messages?roomId[$in][]=2&roomId[$in][]=5
```
### $lt, $lte
Find all records where the value is less (`$lt`) or less and equal (`$lte`) to a given value.
```js
// Find all messages older than a day
const DAY_MS = 24 * 60 * 60 * 1000
app.service('messages').find({
query: {
createdAt: {
$lt: new Date().getTime() - DAY_MS
}
}
})
```
```
GET /messages?createdAt[$lt]=1479664146607
```
### $gt, $gte
Find all records where the value is more (`$gt`) or more and equal (`$gte`) to a given value.
```js
// Find all messages within the last day
const DAY_MS = 24 * 60 * 60 * 1000
app.service('messages').find({
query: {
createdAt: {
$gt: new Date().getTime() - DAY_MS
}
}
})
```
```
GET /messages?createdAt[$gt]=1479664146607
```
### $ne
Find all records that do not equal the given property value.
```js
// Find all messages that are not marked as archived
app.service('messages').find({
query: {
archived: {
$ne: true
}
}
})
```
```
GET /messages?archived[$ne]=true
```
## Search
Searching is not part of the common querying syntax since it is very specific to the database you are using. For built in databases, see the [SQL search](./knex.md#search) and [MongoDb search](./mongodb.md#search) documentation. If you are using [a community supported adapter](/ecosystem/?cat=Database&sort=lastPublish) their documentation may contain additional information on how to implement search functionality.