Document Service API: Selecting fields

Page summary:

Use the fields parameter in Document Service API queries to select specific fields to return with your results, reducing data payload across findOne(), findMany(), create(), update(), delete(), publish(), and other document operations.

By default the Document Service API returns all the fields of a document but does not populate any fields. This page describes how to use the fields parameter to return only specific fields with the query results.

Tip

You can also use the populate parameter to populate relations, media fields, components, or dynamic zones (see the populate parameter documentation).

Note

Though it's recommended to target entries by their documentId in Strapi 5, entries might still have an id field, and you will see it in the returned response. This should ease your transition from Strapi 4. Please refer to the breaking change entry for more details.

Select fields with findOne() queries

strapi.documents("api::restaurant.restaurant").findOne()

Select fields with findOne()

Select specific fields to return when finding a document by documentId.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  fields: ["name", "description"],
});

200 OK

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

Select fields with findFirst() queries

strapi.documents("api::restaurant.restaurant").findFirst()

Select fields with findFirst()

Select specific fields to return when finding the first matching document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  fields: ["name", "description"],
});

200 OK

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

Select fields with findMany() queries

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

Select fields with findMany()

Select specific fields to return when finding multiple documents.

JavaScript

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  fields: ["name", "description"],
});

200 OK

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    description: "Welcome to Biscotte restaurant! …"
  }
  // ...
]

Select fields with create() queries

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

Select fields with create()

Select specific fields to return when creating a new document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").create({
  data: {
    name: "Restaurant B",
    description: "Description for the restaurant",
  },
  fields: ["name", "description"],
});

200 OK

{
  id: 4,
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant B',
  description: 'Description for the restaurant'
}

Select fields with update() queries

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

Select fields with update()

Select specific fields to return when updating a document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").update({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  data: {
    name: "Restaurant C",
  },
  fields: ["name"],
});

200 OK

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant C'
}

Select fields with delete() queries

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

Select fields with delete()

Select specific fields to return when deleting a document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").delete({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

200 OK

  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the deleted document's versions are returned
  entries: [
    {
      id: 4,
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant C',
      // …
    }
  ]
}

Select fields with publish() queries

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

Select fields with publish()

Select specific fields to return when publishing a document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").publish({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

200 OK

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the published locale entries are returned
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

Select fields with unpublish() queries

strapi.documents("api::restaurant.restaurant").unpublish()

Select fields with unpublish()

Select specific fields to return when unpublishing a document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").unpublish({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  fields: ["name"],
});

200 OK

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the published locale entries are returned
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

Select fields with discardDraft() queries

strapi.documents("api::restaurant.restaurant").discardDraft()

Select fields with discardDraft()

Select specific fields to return when discarding a draft document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").discardDraft({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

200 OK

{
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  // All of the discarded draft entries are returned
  entries: [
    {
      "name": "Restaurant B"
    }
  ]
}