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

🌐 Single Operations with the Query Engine API

Caution

在大多数情况下，你不应该使用查询引擎 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 的最新功能，如草稿与发布、国际化、内容历史记录等，可能还有更多功能。这也意味着查询引擎 API 将无法使用 documentId，而将使用 id，这可能会在数据库层面导致未预料的后果，或者与 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. This also means that the Query Engine API will not be able to use documentId and will use id, which means it could lead to unattended consequences at the database level or partial or incomplete compatibility with Strapi 5 features.

Prerequisites

在深入了解查询引擎 API 文档之前，建议你阅读以下介绍：

🌐 Before diving deeper into the Query Engine API documentation, it is recommended that you read the following introductions:

• 关于后端自定义介绍，
• 以及 内容 API 介绍。

findOne()

Note

只有在文档服务的findOne()方法无法满足你的使用场景时，才使用查询引擎的findOne()方法。

查找与参数匹配的第一个条目。

🌐 Finds the first entry matching the parameters.

语法：findOne(parameters) ⇒ Entry

🌐 Syntax: findOne(parameters) ⇒ Entry

参数

🌐 Parameters | 参数 | 类型 | 描述 || --- | --- | --- || select | 字符串，或字符串数组 | 要返回的属性 || where | WhereParameter | 要使用的过滤器 || offset | 整数 | 要跳过的条目数量 || orderBy | OrderByParameter | 排序 定义 || populate | PopulateParameter | 要填充的关系 |

例子

🌐 Example

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

findMany()

Note

只有在文档服务 findMany() 方法无法满足你的使用场景时，才使用查询引擎的 findMany() 方法。

查找与参数匹配的条目。

🌐 Finds entries matching the parameters.

语法：findMany(parameters) ⇒ Entry[]

🌐 Syntax: findMany(parameters) ⇒ Entry[]

参数

🌐 Parameters | 参数 | 类型 | 描述 || --- | --- | --- || select | 字符串或字符串数组 | 要返回的属性 || where | WhereParameter | 要使用的过滤器 || limit | 整数 | 要返回的条目数量 || offset | 整数 | 要跳过的条目数量 || orderBy | OrderByParameter | 排序定义 || populate | PopulateParameter | 要填充的关联关系 |

例子

🌐 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 | 要填充的关联关系 |

例子

🌐 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

只有在文档服务 create() 方法无法覆盖你的使用场景时，才使用查询引擎的 create() 方法。

创建一个条目并返回它。

🌐 Creates one entry and returns it.

语法：create(parameters) => Entry

🌐 Syntax: create(parameters) => Entry

参数

🌐 Parameters | 参数 | 类型 | 描述 || --- | --- | --- || select | 字符串，或字符串数组 | 要返回的属性 || populate | PopulateParameter | 要填充的关联 || data | 对象 | 输入数据 |

例子

🌐 Example

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

update()

Note

只有在文档服务 update() 方法无法满足你的使用场景时，才使用查询引擎的 update() 方法。

更新一项并返回它。

🌐 Updates one entry and returns it.

语法：update(parameters) => Entry

🌐 Syntax: update(parameters) => Entry

参数

🌐 Parameters | 参数 | 类型 | 描述 || --- | --- | --- || select | 字符串，或字符串数组 | 要返回的 属性 || populate | PopulateParameter | 要 填充 的关系 || where | WhereParameter | 要使用的 过滤器 || data | 对象 | 输入数据 |

例子

🌐 Example

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

delete()

Note

只有在文档服务 delete() 方法无法满足你的使用场景时，才使用查询引擎的 delete() 方法。

删除一项并将其返回。

🌐 Deletes one entry and returns it.

语法：delete(parameters) => Entry

🌐 Syntax: delete(parameters) => Entry

参数

🌐 Parameters | 参数 | 类型 | 描述 || --- | --- | --- || select | 字符串，或字符串数组 | 要返回的属性 || populate | PopulateParameter | 要填充的关系 || where | WhereParameter | 要使用的过滤器 |

例子

🌐 Example

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