使用查询引擎 API 进行批量操作

页面摘要： 使用查询引擎 API 的批量操作，可通过 createMany()、updateMany()、deleteMany() 与 count() 方法一次性创建、更新、删除并统计多个条目。

WARNING

大多数情况下你不应使用 Query Engine API，而应使用 Document Service API。

只有当你能确定自己在做什么时才使用 Query Engine API，例如需要直接与数据库唯一行交互的底层 API。

请注意，Query Engine API 无法感知 Strapi 5 的高级功能，如草稿与发布、国际化、内容历史等。这也意味着 Query Engine API 无法使用 documentId，而会使用 id，这可能导致数据库层面的意外后果，或与 Strapi 5 功能出现部分或不完整的兼容性问题。

WARNING

在深入阅读 Query Engine API 文档之前，建议你先阅读以下介绍：

后端自定义介绍，
以及 Content APIs 介绍。

WARNING

为避免性能问题，批量操作不允许在关联上使用。

createMany()

创建多个条目。

语法：createMany(parameters) => { count: number, ids: id[] }

参数

参数	类型	说明
`data`	对象数组	输入数据数组

WARNING

MySQL 只会返回一个包含最后插入 id 的数组（即单个 id），而非完整列表。
在 Strapi v4.9.0 之前，createMany() 仅返回 count。

示例

await strapi.db.query("api::blog.article").createMany({
  data: [
    {
      title: "ABCD",
    },
    {
      title: "EFGH",
    },
  ],
});

// { count: 2 , ids: [1,2]}

updateMany()

更新与参数匹配的多个条目。

语法：updateMany(parameters) => { count: number }

参数

参数	类型	说明
`where`	`WhereParameter`	要使用的过滤器
`data`	对象	输入数据

示例

await strapi.db.query("api::shop.article").updateMany({
  where: {
    price: 20,
  },
  data: {
    price: 18,
  },
});

// { count: 42 }

deleteMany()

删除与参数匹配的多个条目。

语法：deleteMany(parameters) => { count: number }

参数

参数	类型	说明
`where`	`WhereParameter`	要使用的过滤器

示例

await strapi.db.query("api::blog.article").deleteMany({
  where: {
    title: {
      $startsWith: "v3",
    },
  },
});

// { count: 42 }

聚合（Aggregations）

count()

统计与参数匹配的条目数量。

语法：count(parameters) => number

参数

参数	类型	说明
`where`	`WhereParameter`	要使用的过滤器

const count = await strapi.db.query("api::blog.article").count({
  where: {
    title: {
      $startsWith: "v3",
    },
  },
});

// 12