CRUD operations with the Entity Service API

Caution

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

The Entity Service API is built on top of the the Query Engine API and uses it to perform CRUD operations on entities.

The uid parameter used in function calls for this API is a string built with the following format: [category]::[content-type] where category is one of: admin, plugin or api.

Examples:

• A correct uid to get users of the Strapi admin panel is admin::user.
• A possible uid for the Upload plugin could be plugin::upload.file.
• As the uids for user-defined custom content-types follow the api::[content-type] syntax, if a content-type article exists, it is referenced by api::article.article.

Tip

Run the strapi content-types:list command in a terminal to display all possible content-types' uids for a specific Strapi instance.

findOne()

Finds the first entry matching the parameters.

Syntax: findOne(uid: string, id: ID, parameters: Params) ⇒ Entry

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code (for example fr-FR) when the Internationalization plugin is enabled. Targets the localized variant instead of the default locale.	string

Example

const entry = await strapi.entityService.findOne('api::article.article', 1, {
  fields: ['title', 'description'],
  populate: { category: true },
});

findMany()

Finds entries matching the parameters.

Syntax: findMany(uid: string, parameters: Params) ⇒ Entry[]

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
filters	Filters to use	FiltersParameters
start	Number of entries to skip (see pagination)	Number
limit	Number of entries to return (see pagination)	Number
sort	Order definition	OrderByParameter
populate	Relations, components and dynamic zones to populate	PopulateParameter
publicationState	Publication state, can be: live to return only published entries preview to return both draft entries & published entries (default)	PublicationStateParameter
locale	Locale code when the Internationalization plugin is enabled. Restricts results to that locale (omit for the default locale).	string

Example

const entries = await strapi.entityService.findMany('api::article.article', {
  fields: ['title', 'description'],
  filters: { title: 'Hello World' },
  sort: { createdAt: 'DESC' },
  populate: { category: true },
});

Tip

To retrieve only draft entries, combine the preview publication state and the publishedAt fields:

const entries = await strapi.entityService.findMany('api::article.article', {
  publicationState: 'preview',
  filters: {
    publishedAt: {
      $null: true,
    },
  },
});

create()

Creates one entry and returns it

Syntax: create(uid: string, parameters: Params) ⇒ Entry

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code when the Internationalization plugin is enabled. Creates the entry for that locale.	string
data	Input data	Object

Tip

In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

Example

const entry = await strapi.entityService.create('api::article.article', {
  data: {
    title: 'My Article',
  },
});

update()

Updates one entry and returns it.

Note

update() only performs a partial update, so existing fields that are not included won't be replaced.

Syntax: update(uid: string, id: ID, parameters: Params) ⇒ Entry

Tip

In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code when the Internationalization plugin is enabled. Updates the matching localized variant.	string
data	Input data	object

Example

const entry = await strapi.entityService.update('api::article.article', 1, {
  data: {
    title: 'xxx',
  },
});

delete()

Deletes one entry and returns it.

Syntax: delete(uid: string, id: ID, parameters: Params) ⇒ Entry

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code when the Internationalization plugin is enabled. Deletes the localized variant that matches this locale.	string

Example

const entry = await strapi.entityService.delete('api::article.article', 1);