import ManagingRelations from '/docs/snippets/managing-relations.md'
import ESdeprecated from '/docs/snippets/entity-service-deprecated.md'

CRUD operations with the Entity Service API#

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.

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`

Example#

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

update()#

Updates one entry and returns it.

Syntax: update(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. 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);