Skip to main content

Entity Service API

✋ Caution

The Entity Service API will be deprecated in Strapi v5. Please consider using the Document Service API instead.

☑️ Prerequisites

Before diving deeper into the Entity Service API documentation, it is recommended that you read the following introductions:

The Strapi backend provides an Entity Service API, built on top of the Query Engine API. The Entity Service is the layer that handles Strapi's complex data structures like components and dynamic zones, and uses the Query Engine API under the hood to execute database queries.

🤓 Entity Service API vs. Query Engine API

Strapi v4 offers several layers to interact with the backend and build your queries:

  • The Document Service API is the recommended API to interact with your application's database. The Document Service is the layer that handles Strapi's document model and the complex data structures like components and dynamic zones, which the lower-level layers are not aware of.
  • The Query Engine API interacts with the database layer at a lower level and is used under the hood to execute database queries. It gives unrestricted internal access to the database layer, but should be used only if the Document Service API does not cover your use case.
  • If you need direct access to knex functions, use strapi.db.connection.
👀 Disambiguation: Services vs. Entity Service

While services can use the Entity Service API, services and the Entity Service API are not directly related. You can find more information about the core elements of the Strapi back end in the back-end customization documentation.

Basic usage​

The Entity Service is available through strapi.entityService:

const entry = await strapi.entityService.findOne('api::article.article', 1, {
  populate: { someRelation: true },
});

Available operations​

The Entity Service API allows the following operations on entities: