Document Service API: Populating fields

Page summary:

Use the populate parameter with the Document Service API to explicitly load relations, media fields, components, and dynamic zones at one or multiple levels deep, and within create(), update(), publish(), and delete() operations.

By default the Document Service API does not populate any relations, media fields, components, or dynamic zones. This page describes how to use the populate parameter to populate specific fields.

Tip

You can also use the select parameter to return only specific fields with the query results (see the select parameter documentation).

Caution

If the Users & Permissions plugin is installed, the find permission must be enabled for the content-types that are being populated. If a role doesn't have access to a content-type it will not be populated.

Relations and media fields

Queries can accept a populate parameter to explicitly define which fields to populate, with the following syntax option examples. This includes all relation types: one-to-many, many-to-one, many-to-many, and polymorphic relations (morphToOne, morphToMany).

Populate 1 level for all relations

strapi.documents("api::article.article").findMany()

Populate 1 level for all relations

Populate one-level deep for all relations using the wildcard.

Populate 1 level for specific relations

strapi.documents("api::article.article").findMany()

Populate 1 level for specific relations

Populate specific relations one-level deep using an array.

Populate several levels deep for specific relations

strapi.documents("api::article.article").findMany()

Populate several levels deep for specific relations

Populate specific relations several levels deep using nested populate.

Sort populated relations

Use the sort parameter inside a populate object to order related entries by an attribute. For many-to-many and other join-table relations, an explicit sort takes precedence over the default connect order.

strapi.documents("api::article.article").findMany()

Sort populated relations

Order related entries by an attribute using the sort parameter inside a populate object.

Note

Omit sort from a populate object to preserve the default connect order (the order in which entries were associated).

Components & Dynamic Zones

Components are populated the same way as relations:

strapi.documents("api::article.article").findMany()

Populate components

Populate components using the same syntax as relations.

Dynamic zones are highly dynamic content structures by essence. Standard populate queries (like populate: '*' or populate: ['testDZ']) will only retrieve the default, non-relational scalar fields (e.g., strings, numbers) of components within a dynamic zone. They will not automatically fetch nested relations, media fields, or nested components.

To populate component-specific nested relations, media fields, or components within a dynamic zone, you must define per-component populate queries using the on property (fragment population syntax).

strapi.documents("api::article.article").findMany()

Populate dynamic zones

Populate dynamic zones using per-component queries with the on property.

Populating with create()

strapi.documents("api::article.article").create()

Populate with create

Populate relations in the response when creating a document.

Populating with update()

strapi.documents("api::article.article").update()

Populate with update

Populate relations in the response when updating a document.

Populating with publish()

Same behavior applies with unpublish() and discardDraft().

strapi.documents("api::article.article").publish()

Populate with publish

Populate relations in the response when publishing a document.

Populating with delete()

To populate while deleting documents:

strapi.documents("api::article.article").delete()

Populate with delete

Populate relations in the response when deleting a document.