Skip to main content

CRUD operations

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.

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​

ParameterDescriptionType
fieldsAttributes to returnString[]
populateRelations, components and dynamic zones to populatePopulateParameter

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​

ParameterDescriptionType
fieldsAttributes to returnString[]
filtersFilters to useFiltersParameters
startNumber of entries to skip (see pagination)Number
limitNumber of entries to return (see pagination)Number
sortOrder definitionOrderByParameter
populateRelations, components and dynamic zones to populatePopulateParameter
publicationStatePublication state, can be:
  • live to return only published entries
  • preview to return both draft entries & published entries (default)
PublicationStateParameter
note

For single types, "findMany" returns the entry data as an object instead of an array of entries.

Example​

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

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](/dev-docs/api/entity-service/populate) | [`PopulateParameter`](/dev-docs/api/entity-service/populate) |
| `data` | Input data | `Object` |



### Example

```js
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

Parameters​

ParameterDescriptionType
fieldsAttributes to returnString[]
populateRelations, components and dynamic zones to populatePopulateParameter
dataInput dataobject

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​

ParameterDescriptionType
fieldsAttributes to returnString[]
populateRelations, components and dynamic zones to populatePopulateParameter

Example​

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