288 lines
5.4 KiB
Markdown
Raw Normal View History

2019-05-16 21:37:45 +02:00
# Queries
2019-08-12 16:58:18 +02:00
Strapi provides a utility function `strapi.query` to make database queries.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
You can just call `strapi.query(modelName, pluginName)` to access the query API for any model.
2019-05-16 21:37:45 +02:00
2019-08-13 10:41:11 +02:00
These queries handle for you specific Strapi features like `groups`, `filters` and `search`.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
## API Reference
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### `findOne`
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
This method returns the first entry matching some basic params.
You can also pass a populate option to specify which relations you want to be populated.
#### Examples
**Find one by id**:
2019-05-16 21:37:45 +02:00
```js
2019-08-12 16:58:18 +02:00
strapi.query('post').findOne({ id: 1 });
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find one by title**:
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').findOne({ title: 'my title' });
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find one by title and creation_date**:
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi
.query('post')
2019-08-13 10:41:11 +02:00
.findOne({ title: 'my title', date: '2019-01-01T00:00:00Z' });
2019-08-12 16:58:18 +02:00
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find one by id and populate a relation**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').findOne({ id: 1 }, ['tag', 'tag.picture']);
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### `find`
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
This method returns a list of entries matching Strapi filters.
You can also pass a populate option to specify which relations you want to be populated.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
#### Examples
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find by id**:
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').find({ id: 1 });
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find by in IN, with a limit**:
```js
strapi.query('post').find({ _limit: 10, id_in: [1, 2] });
2019-05-16 21:37:45 +02:00
```
2019-08-12 16:58:18 +02:00
**Find by date orderBy title**:
2019-05-16 21:37:45 +02:00
```js
2019-08-12 16:58:18 +02:00
strapi
.query('post')
.find({ date_gt: '2019-01-01T00:00:00Z', _sort: 'title:desc' });
2019-08-12 16:58:18 +02:00
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Find by id not in and populate a relation. Skip the first ten results**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').find({ id_nin: [1], _start: 10 }, ['tag', 'tag.picture']);
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### `create`
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
Creates an entry in the database and returns the entry.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
#### Example
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').create({
title: 'Mytitle',
// this is a group field. the order is persisted in db.
seo: [
{
metadata: 'description',
value: 'My description',
},
{
metadata: 'keywords',
value: 'someKeyword,otherKeyword',
},
],
// pass the id of a media to link it to the entry
picture: 1,
// automatically creates the relations when passing the ids in the field
tags: [1, 2, 3],
});
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### `update`
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
Updates an entry in the database and returns the entry.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
#### Examples
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Update by id**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').update(
{ id: 1 },
{
title: 'Mytitle',
seo: [
{
metadata: 'description',
value: 'My description',
},
{
metadata: 'keywords',
value: 'someKeyword,otherKeyword',
},
],
// pass the id of a media to link it to the entry
picture: 1,
// automatically creates the relations when passing the ids in the field
tags: [1, 2, 3],
}
);
```
2019-05-16 21:37:45 +02:00
When updating an entry with its groups beware that if you send the groups without any `id` the previous groups will be deleted and replaced. You can update the groups by sending their `id` with the rest of the fields:
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Update by id and update previous groups**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').update(
{ id: 1 },
{
title: 'Mytitle',
seo: [
{
id: 2
metadata: 'keywords',
value: 'someKeyword,otherKeyword',
},
{
id: 1
metadata: 'description',
value: 'My description',
}
],
// pass the id of a media to link it to the entry
picture: 1,
// automatically creates the relations when passing the ids in the field
tags: [1, 2, 3],
}
);
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Partial update by title**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').update(
{ title: 'specific title' },
{
title: 'Mytitle',
}
);
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### `delete`
2019-05-16 21:37:45 +02:00
2019-08-13 10:41:11 +02:00
Deletes and entry and return its value before deletion.
2019-08-12 16:58:18 +02:00
You can delete multiple entries at once with the passed params.
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
#### Examples
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Delete one by id**
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
```js
strapi.query('post').delete({ id: 1 });
```
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
**Delete multiple by field**
```js
strapi.query('post').delete({ lang: 'en' });
2019-05-16 21:37:45 +02:00
```
2019-08-12 16:58:18 +02:00
### `count`
2019-05-16 21:37:45 +02:00
Returns the count of entries matching Strapi filters.
#### Examples
**Count by lang**
```js
strapi.query('post').count({ lang: 'en' });
```
**Count by title contains**
```js
strapi.query('post').count({ title_contains: 'food' });
```
**Count by date less than**
```js
strapi.query('post').count({ date_lt: '2019-08-01T00:00:00Z' });
```
2019-08-12 16:58:18 +02:00
### `search`
2019-05-16 21:37:45 +02:00
2019-08-13 10:41:11 +02:00
Returns entries based on a search on all fields allowing it. (this feature will return all entries on sqlite).
#### Examples
**Search first ten starting at 20**
```js
strapi.query('post').search({ _q: 'my search query', _limit: 10, _start: 20 });
```
**Search and sort**
```js
strapi
.query('post')
.search({ _q: 'my search query', _limit: 100, _sort: 'date:desc' });
```
2019-08-12 16:58:18 +02:00
### `countSearch`
2019-05-16 21:37:45 +02:00
2019-08-13 10:41:11 +02:00
Returns the total count of entries based on a search. (this feature will return all entries on sqlite).
#### Example
```js
strapi.query('post').countSearch({ _q: 'my search query' });
```
2019-08-12 16:58:18 +02:00
## Custom Queries
2019-05-16 21:37:45 +02:00
When you want to customize your services or create new ones you will have to build your queries with the underlying ORM models.
2019-05-16 21:37:45 +02:00
To access the underlying model:
```js
strapi.query(modelName, plugin).model;
```
2019-05-16 21:37:45 +02:00
Then you can run any queries available on the model. You should refer to the specific ORM documentation for more details:
2019-05-16 21:37:45 +02:00
2019-08-12 16:58:18 +02:00
### Bookshelf
Documentation: [https://bookshelfjs.org/](https://bookshelfjs.org/)
2019-08-12 16:58:18 +02:00
**Example**
2019-08-12 16:58:18 +02:00
```js
strapi
.query('post')
.model.query(qb => {
qb.where('id', 1);
})
.fetch();
```
### Mongoose
Documentation: [https://mongoosejs.com/](https://mongoosejs.com/)
**Example**
```js
strapi
.query('post')
.model.find({
{ date: { $gte: '2019-01-01T00.00.00Z }
});
```