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.

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#

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

const documents = await strapi.documents("api::article.article").findMany({
  populate: "*",
});

{
  [
    {
      "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:

const documents = await strapi.documents("api::article.article").findMany({
  populate: ["headerImage"],
});

[
  {
    "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:

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    categories: {
      populate: ["articles"],
    },
  },
});

[
  {
    "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",
          // ...
        }
        // ...
      ]
    }
  }
  // ...
]

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.

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    categories: {
      sort: 'name:asc',
    },
  },
});

[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    // ...
    "categories": [
      {
        "id": 1,
        "name": "Architecture"
        // ...
      },
      {
        "id": 3,
        "name": "Technology"
        // ...
      }
    ]
  }
  // ...
]

Components & Dynamic Zones#

Components are populated the same way as relations:

const documents = await strapi.documents("api::article.article").findMany({
  populate: ["testComp"],
});

[
  {
    "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. To populate a dynamic zone, you must define per-component populate queries using the on property.

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    testDZ: {
      on: {
        "test.test-compo": {
          fields: ["testString"],
          populate: ["testNestedCompo"],
        },
      },
    },
  },
});

[
  {
    "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:

strapi.documents("api::article.article").create({
  data: {
    title: "Test Article",
    slug: "test-article",
    body: "Test 1",
    headerImage: 2,
  },
  populate: ["headerImage"],
});

{
  "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:

strapi.documents("api::article.article").update({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  data: {
    title: "Test Article Update",
  },
  populate: ["headerImage"],
});

{
  "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()):

strapi.documents("api::article.article").publish({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  populate: ["headerImage"],
});

{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "versions": [
    {
      "id": "cjld2cjxh0001qzrm1q1i7rn",
      "locale": "en",
      // ...
      "headerImage": {
        "id": 2,
        "name": "17520.jpg"
        // ...
      }
    }
  ]
}

Populating with `delete()`#

To populate while deleting documents:

strapi.documents("api::article.article").delete({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  populate: ["headerImage"],
});

{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "entries": [
    {
      "id": "cjld2cjxh0000qzrmn831i7rn",
      "title": "Test Article",
      "slug": "test-article",
      "body": "Test 1",
      "headerImage": {
        "id": 2,
        "name": "17520.jpg"
        // ...
      }
      // ...
    }
  ]
}