Populating with the Query Engine API

🏗 Work in progress

The content of this page might not be fully up-to-date with Strapi 5 yet.

🤓 Have you considered the Document Service API?

The Document Service API is the recommended API to interact with your application's database. Only use the Query Engine API if the Document Service API does not cover your use case.

Relations and components have a unified API for populating them.

To populate all the root level relations, use populate: true:

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

Select which data to populate by passing an array of attribute names:

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

An object can be passed for more advanced usage:

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

Complex populating can also be achieved by applying where filters and select or populate nested relations:

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

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

    dynamiczoneA: true,
  },
});

When dealing with polymorphic data structures (dynamic zones, polymorphic relations, etc...), it is possible to use populate fragments to have a better granularity on the populate strategy.

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'],
        },
      },
    },
  },
});