Skip to main content

Document Service API: Populating fields

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.

Populate 1 level for all relations​

To populate one-level deep for all relations, use the * wildcard in combination with the populate parameter:

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: "*",
});
Example response
{
  [
    {
      "id": "cjld2cjxh0000qzrmn831i7rn",
      "title": "Test Article",
      "slug": "test-article",
      "body": "Test 1",
      // ...
      "headerImage": {
        "data": {
          "id": 1,
          "attributes": {
            "name": "17520.jpg",
            "alternativeText": "17520.jpg",
            "formats": {
              // ...
            }
            // ...
          }
        }
      },
      "author": {
        // ...
      },
      "categories": {
        // ...
      }
    }
    // ...
  ]
}

Populate 1 level for specific relations​

To populate specific relations one-level deep, pass the relation names in a populate array:

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: ["headerImage"],
});
Example response
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "headerImage": {
      "id": 2,
      "name": "17520.jpg"
      // ...
    }
  }
  // ...
]

Populate several levels deep for specific relations​

To populate specific relations several levels deep, use the object format with populate:

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    categories: {
      populate: ["articles"],
    },
  },
});
Example response
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "categories": {
      "id": 1,
      "name": "Test Category",
      "slug": "test-category",
      "description": "Test 1"
      // ...
      "articles": [
        {
          "id": 1,
          "title": "Test Article",
          "slug": "test-article",
          "body": "Test 1",
          // ...
        }
        // ...
      ]
    }
  }
  // ...
]

Components & Dynamic Zones​

Components are populated the same way as relations:

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: ["testComp"],
});
Example response
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "testComp": {
      "id": 1,
      "name": "Test Component"
      // ...
    }
  }
  // ...
]

Dynamic zones are highly dynamic content structures by essence. When populating dynamic zones, you can choose between a shared population strategy or a detailed population strategy.

In a shared population strategy, apply a unique behavior for all the dynamic zone's components.

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    testDZ: "*",
  },
});
Example response
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "testDZ": [
      {
        "id": 3,
        "__component": "test.test-compo",
        "testString": "test1",
        "testNestedCompo": {
          "id": 3,
          "testNestedString": "testNested1"
        },
        "otherField": "test"
      },
      {
        "id": 1,
        "__component": "test.test-compo2",
        "testInt": 1,
        "otherField": "test"
      }
    ]
  }
  // ...
]

With the detailed population strategy, define per-component populate queries using the on property.

Example request
const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    testDZ: {
      on: {
        "test.test-compo": {
          fields: ["testString"],
          populate: ["testNestedCompo"],
        },
      },
    },
  },
});
Example response
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "testDZ": [
      {
        "id": 3,
        "__component": "test.test-compo",
        "testString": "test1",
        "testNestedCompo": {
          "id": 3,
          "testNestedString": "testNested1"
        }
      }
    ]
  }
  // ...
]

Populating with create()​

To populate while creating documents:

Example request
strapi.documents("api::article.article").create({
  data: {
    title: "Test Article",
    slug: "test-article",
    body: "Test 1",
    headerImage: 2,
  },
  populate: ["headerImage"],
});
Example response
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  "headerImage": {
    "id": 2,
    "name": "17520.jpg"
    // ...
  }
}

Populating with update()​

To populate while updating documents:

Example request
strapi.documents("api::article.article").update("cjld2cjxh0000qzrmn831i7rn", {
  data: {
    title: "Test Article Update",
  },
  populate: ["headerImage"],
});
Example response
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article Update",
  "slug": "test-article",
  "body": "Test 1",
  "headerImage": {
    "id": 2,
    "name": "17520.jpg"
    // ...
  }
}

Populating with publish()​

To populate while publishing documents (same behavior with unpublish() and discardDraft()):

Example request
strapi.documents("api::article.article").publish("cjld2cjxh0000qzrmn831i7rn", {
  populate: ["headerImage"],
});
Example response
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "versions": [
    {
      "id": "cjld2cjxh0001qzrm1q1i7rn",
      "locale": "en",
      // ...
      "headerImage": {
        "id": 2,
        "name": "17520.jpg"
        // ...
      }
    }
  ]
}