使用查询引擎 API 联表加载（populate）

页面摘要： 查询引擎 API 的 populate 参数用于在查询中加载关联数据，支持基础联表加载、选择性字段、嵌套关联过滤，以及通过 populate 片段（fragments）处理多态结构。

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 文档之前，建议你先阅读以下介绍：

关联与组件共用一套统一的 API 来进行联表加载。

要联表加载所有根级关联，可使用 populate: true：

strapi.db.query('api::article.article').findMany({
  populate: true,
});

通过传入属性名数组，选择要联表加载的数据：

strapi.db.query('api::article.article').findMany({
  populate: ['componentA', 'relationA'],
});

可传入一个对象以进行更高级的用法：

strapi.db.query('api::article.article').findMany({
  populate: {
    componentB: true,
    dynamiczoneA: true,
    relation: someLogic || true,
  },
});

通过应用 where 过滤器并选择或联表加载嵌套关联，也可实现复杂的联表加载：

strapi.db.query('api::article.article').findMany({
  populate: {
    relationA: {
      where: {
        name: {
          $contains: 'Strapi',
        },
      },
    },

    repeatableComponent: {
      select: ['someAttributeName'],
      orderBy: ['someAttributeName'],
      populate: {
        componentRelationA: true,
      },
    },

    dynamiczoneA: true,
  },
});

在处理多态内容结构（动态区域、多态关联等）时，可使用 populate 片段，以更精细地控制联表加载策略。

strapi.db.query('api::article.article').findMany('api::article.article', {
  populate: {
    dynamicZone: {
      on: {
        'components.foo': {
          select: ['title'],
          where: { title: { $contains: 'strapi' } },
        },
        'components.bar': {
          select: ['name'],
        },
      },
    },

    morphAuthor: {
      on: {
        'plugin::users-permissions.user': {
          select: ['username'],
        },
        'api::author.author': {
          select: ['name'],
        },
      },
    },
  },
});