使用查询引擎的单一操作 API

¥Single Operations with the Query Engine API

✋ 提醒

在大多数情况下，你不应使用查询引擎 API，而应使用 文档服务 API。

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

仅当你确切知道自己在做什么时才使用查询引擎 API，例如，如果你想使用直接与数据库的唯一行交互的底层 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.

请记住，查询引擎 API 不了解最高级的 Strapi 5 功能，如草稿和发布、国际化、内容历史记录等。

¥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()

✏️ 注意

仅当 文档服务的 findOne() 方法无法覆盖你的用例时才使用查询引擎的 findOne() 方法。

¥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.

语法：findOne(parameters) ⇒ Entry

¥Syntax: findOne(parameters) ⇒ Entry

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
where	WhereParameter	使用 过滤器
offset	整数	要跳过的条目数
orderBy	OrderByParameter	命令 定义
populate	PopulateParameter	与 populate 的关系

示例

¥Example

const entry = await strapi.db.query('api::blog.article').findOne({


  select: ['title', 'description'],
  where: { title: 'Hello World' },
  populate: { category: true },
});

findMany()

✏️ 注意

仅当 文档服务 findMany() 方法无法覆盖你的用例时才使用查询引擎的 findMany() 方法。

¥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.

语法：findMany(parameters) ⇒ Entry[]

¥Syntax: findMany(parameters) ⇒ Entry[]

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
where	WhereParameter	使用 过滤器
limit	整数	要返回的条目数
offset	整数	要跳过的条目数
orderBy	OrderByParameter	命令 定义
populate	PopulateParameter	与 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.

语法：findWithCount(parameters) => [Entry[], number]

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

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
where	WhereParameter	使用 过滤器
limit	整数	要返回的条目数
offset	整数	要跳过的条目数
orderBy	OrderByParameter	命令 定义
populate	PopulateParameter	与 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()

✏️ 注意

仅当 文档服务 create() 方法 无法覆盖你的用例时才使用查询引擎的 create() 方法。

¥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.

语法：create(parameters) => Entry

¥Syntax: create(parameters) => Entry

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
populate	PopulateParameter	与 populate 的关系
data	目的	输入数据

示例

¥Example

const entry = await strapi.db.query('api::blog.article').create({


  data: {
    title: 'My Article',
  },
});

💡 提示

在 data 对象中，可以使用 REST API 描述的语法通过 connect、disconnect 和 set 参数来管理关系（请参阅 管理关系）。

¥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()

✏️ 注意

仅当 文档服务 update() 方法无法覆盖你的用例时才使用查询引擎的 update() 方法。

¥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.

语法：update(parameters) => Entry

¥Syntax: update(parameters) => Entry

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
populate	PopulateParameter	与 populate 的关系
where	WhereParameter	使用 过滤器
data	目的	输入数据

示例

¥Example

const entry = await strapi.db.query('api::blog.article').update({


  where: { id: 1 },
  data: {
    title: 'xxx',
  },
});

💡 提示

在 data 对象中，可以使用 REST API 描述的语法通过 connect、disconnect 和 set 参数来管理关系（请参阅 管理关系）。

¥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()

✏️ 注意

仅当 文档服务 delete() 方法无法覆盖你的用例时才使用查询引擎的 delete() 方法。

¥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.

语法：delete(parameters) => Entry

¥Syntax: delete(parameters) => Entry

参数

¥Parameters

范围	类型	描述
select	字符串或字符串数组	属性 返回
populate	PopulateParameter	与 populate 的关系
where	WhereParameter	使用 过滤器

示例

¥Example

const entry = await strapi.db.query('api::blog.article').delete({


  where: { id: 1 },
});