Single Operations with the Query Engine API

✋ Caution

In most cases you should not use the Query Engine API and rather use the Document Service API.

Only use the Query Engine API if you exactly know what you are doing, for instance if you want to use a lower-level API that directly interacts with unique rows of the database.

Please keep in mind that the Query Engine API is not aware of the most advanced Strapi 5 features like Draft & Publish, Internationalization, Content History, and possibly more.

findOne()

✏️ Note

Only use the Query Engine's findOne() method if the Document Service's findOne() method can't cover your use case.

Finds the first entry matching the parameters.

Syntax: findOne(parameters) ⇒ Entry

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
where	WhereParameter	Filters to use
offset	Integer	Number of entries to skip
orderBy	OrderByParameter	Order definition
populate	PopulateParameter	Relations to populate

Example

const entry = await strapi.db.query('api::blog.article').findOne({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  populate: { category: true },
});

findMany()

✏️ Note

Only use the Query Engine's findMany() method if the Document Service findMany() method can't cover your use case.

Finds entries matching the parameters.

Syntax: findMany(parameters) ⇒ Entry[]

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
where	WhereParameter	Filters to use
limit	Integer	Number of entries to return
offset	Integer	Number of entries to skip
orderBy	OrderByParameter	Order definition
populate	PopulateParameter	Relations to populate

Example

const entries = await strapi.db.query('api::blog.article').findMany({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  orderBy: { publishedAt: 'DESC' },
  populate: { category: true },
});

findWithCount()

Finds and counts entries matching the parameters.

Syntax: findWithCount(parameters) => [Entry[], number]

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
where	WhereParameter	Filters to use
limit	Integer	Number of entries to return
offset	Integer	Number of entries to skip
orderBy	OrderByParameter	Order definition
populate	PopulateParameter	Relations to populate

Example

const [entries, count] = await strapi.db.query('api::blog.article').findWithCount({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  orderBy: { title: 'DESC' },
  populate: { category: true },
});

create()

✏️ Note

Only use the Query Engine's create() method if the Document Service create() method can't cover your use case.

Creates one entry and returns it.

Syntax: create(parameters) => Entry

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
populate	PopulateParameter	Relations to populate
data	Object	Input data

Example

const entry = await strapi.db.query('api::blog.article').create({
  data: {
    title: 'My Article',
  },
});

💡 Tip

In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

update()

✏️ Note

Only use the Query Engine's update() method if the Document Service update() method can't cover your use case.

Updates one entry and returns it.

Syntax: update(parameters) => Entry

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
populate	PopulateParameter	Relations to populate
where	WhereParameter	Filters to use
data	Object	Input data

Example

const entry = await strapi.db.query('api::blog.article').update({
  where: { id: 1 },
  data: {
    title: 'xxx',
  },
});

💡 Tip

In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

delete()

✏️ Note

Only use the Query Engine's delete() method if the Document Service delete() method can't cover your use case.

Deletes one entry and returns it.

Syntax: delete(parameters) => Entry

Parameters

Parameter	Type	Description
select	String, or Array of strings	Attributes to return
populate	PopulateParameter	Relations to populate
where	WhereParameter	Filters to use

Example

const entry = await strapi.db.query('api::blog.article').delete({
  where: { id: 1 },
});