# 单次操作

> Source: https://strapi.nodejs.cn/cms/api/query-engine/single-operations

🌐 Single Operations with the Query Engine API

查询引擎 API 提供了方法来查找、创建、更新和删除单个条目，并支持过滤、选择、分页和关联填充选项。

🌐 The Query Engine API provides methods to find, create, update, and delete individual entries with filtering, selection, pagination, and relation population options.

:::caution

在大多数情况下，你不应该使用查询引擎 API，而应使用 [文档服务 API](/cms/api/document-service)。

🌐 In most cases you should not use the Query Engine API and rather use the [Document Service API](/cms/api/document-service).

仅当你确切知道自己在做什么时才使用查询引擎 API，例如，如果你想使用直接与数据库的唯一行交互的底层 API。

🌐 Only use the Query Engine API if you exactly know what you are doing, for instance if you want to use a lower-level API that directly interacts with unique rows of the database.

请记住，查询引擎 API 并不了解 Strapi 5 的最新功能，如草稿与发布、国际化、内容历史记录等，可能还有更多功能。这也意味着查询引擎 API 将无法使用 `documentId`，而将使用 `id`，这可能会在数据库层面导致未预料的后果，或者与 Strapi 5 功能存在部分或不完全兼容的情况。 

🌐 Please keep in mind that the Query Engine API is not aware of the most advanced Strapi 5 features like Draft & Publish, Internationalization, Content History, and possibly more.
This also means that the Query Engine API will not be able to use `documentId` and will use `id`, which means it could lead to unattended consequences at the database level or partial or incomplete compatibility with Strapi 5 features. 

:::

:::prerequisites

在深入了解查询引擎 API 文档之前，建议你阅读以下介绍：

🌐 Before diving deeper into the Query Engine API documentation, it is recommended that you read the following introductions:

- 关于[后端自定义介绍](/cms/backend-customization)，
- 以及 [内容 API 介绍](/cms/api/content-api)。

:::

## findOne()

:::note

 只有在[文档服务的`findOne()`](/cms/api/document-service#findone)方法无法满足你的使用场景时，才使用查询引擎的`findOne()`方法。

:::

查找与参数匹配的第一个条目。

🌐 Finds the first entry matching the parameters.

语法：`findOne(parameters) ⇒ Entry`

🌐 Syntax: `findOne(parameters) ⇒ Entry`

### 参数 {#parameters}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串，或字符串数组 | 要返回的[属性](/cms/backend-customization/models#model-attributes) |
| `where` | [`WhereParameter`](/cms/api/query-engine/filtering/) | 要使用的[过滤器](/cms/api/query-engine/filtering/) |
| `offset` | 整数 | 要跳过的条目数量 |
| `orderBy` | [`OrderByParameter`](/cms/api/query-engine/order-pagination/) | [排序](/cms/api/query-engine/order-pagination/) 定义 |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要[填充](/cms/api/query-engine/populating/)的关系 |

### 例子 {#example}

🌐 Example

```js
const entry = await strapi.db.query('api::blog.article').findOne({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  populate: { category: true },
});
```

## findMany()

:::note

 只有在[文档服务 `findMany()`](/cms/api/document-service#findmany) 方法无法满足你的使用场景时，才使用查询引擎的 `findMany()` 方法。

:::

查找与参数匹配的条目。

🌐 Finds entries matching the parameters.

语法：`findMany(parameters) ⇒ Entry[]`

🌐 Syntax: `findMany(parameters) ⇒ Entry[]`

### 参数 {#parameters-1}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串或字符串数组 | 要返回的[属性](/cms/backend-customization/models#model-attributes) |
| `where` | [`WhereParameter`](/cms/api/query-engine/filtering/) | 要使用的[过滤器](/cms/api/query-engine/filtering/) |
| `limit` | 整数 | 要返回的条目数量 |
| `offset` | 整数 | 要跳过的条目数量 |
| `orderBy` | [`OrderByParameter`](/cms/api/query-engine/order-pagination/) | [排序](/cms/api/query-engine/order-pagination/)定义 |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要[填充](/cms/api/query-engine/populating/)的关联关系 |

### 例子 {#example-1}

🌐 Example

```js
const entries = await strapi.db.query('api::blog.article').findMany({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  orderBy: { publishedAt: 'DESC' },
  populate: { category: true },
});
```

## findWithCount()

查找与参数匹配的条目并对其进行计数。

🌐 Finds and counts entries matching the parameters.

语法：`findWithCount(parameters) => [Entry[], number]`

🌐 Syntax: `findWithCount(parameters) => [Entry[], number]`

### 参数 {#parameters-2}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串或字符串数组 | 要返回的[属性](/cms/backend-customization/models#model-attributes) |
| `where` | [`WhereParameter`](/cms/api/query-engine/filtering/) | 要使用的[过滤器](/cms/api/query-engine/filtering/) |
| `limit` | 整数 | 要返回的条目数量 |
| `offset` | 整数 | 要跳过的条目数量 |
| `orderBy` | [`OrderByParameter`](/cms/api/query-engine/order-pagination/) | [排序](/cms/api/query-engine/order-pagination/)定义 |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要[填充](/cms/api/query-engine/populating/)的关联关系 |

### 例子 {#example-2}

🌐 Example

```js
const [entries, count] = await strapi.db.query('api::blog.article').findWithCount({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  orderBy: { title: 'DESC' },
  populate: { category: true },
});
```

## create()

:::note

 只有在[文档服务 `create()` 方法](/cms/api/document-service#create)无法覆盖你的使用场景时，才使用查询引擎的 `create()` 方法。

:::

创建一个条目并返回它。

🌐 Creates one entry and returns it.

语法：`create(parameters) => Entry`

🌐 Syntax: `create(parameters) => Entry`

### 参数 {#parameters-3}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串，或字符串数组 | 要返回的[属性](/cms/backend-customization/models#model-attributes) |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要[填充](/cms/api/query-engine/populating/)的关联 |
| `data` | 对象 | 输入数据 |

### 例子 {#example-3}

🌐 Example

```js
const entry = await strapi.db.query('api::blog.article').create({
  data: {
    title: 'My Article',
  },
});
```

## update()

:::note

 只有在[文档服务 `update()`](/cms/api/document-service#update) 方法无法满足你的使用场景时，才使用查询引擎的 `update()` 方法。

:::

更新一项并返回它。

🌐 Updates one entry and returns it.

语法：`update(parameters) => Entry`

🌐 Syntax: `update(parameters) => Entry`

### 参数 {#parameters-4}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串，或字符串数组 | 要返回的 [属性](/cms/backend-customization/models#model-attributes) |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要 [填充](/cms/api/query-engine/populating/) 的关系 |
| `where` | [`WhereParameter`](/cms/api/query-engine/filtering/) | 要使用的 [过滤器](/cms/api/query-engine/filtering/) |
| `data` | 对象 | 输入数据 |

### 例子 {#example-4}

🌐 Example

```js
const entry = await strapi.db.query('api::blog.article').update({
  where: { id: 1 },
  data: {
    title: 'xxx',
  },
});
```

## delete()

:::note

 只有在[文档服务 `delete()`](/cms/api/document-service#delete) 方法无法满足你的使用场景时，才使用查询引擎的 `delete()` 方法。

:::

删除一项并将其返回。

🌐 Deletes one entry and returns it.

语法：`delete(parameters) => Entry`

🌐 Syntax: `delete(parameters) => Entry`

### 参数 {#parameters-5}

🌐 Parameters

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `select` | 字符串，或字符串数组 | 要返回的[属性](/cms/backend-customization/models#model-attributes) |
| `populate` | [`PopulateParameter`](/cms/api/query-engine/populating/) | 要[填充](/cms/api/query-engine/populating/)的关系 |
| `where` | [`WhereParameter`](/cms/api/query-engine/filtering/) | 要使用的[过滤器](/cms/api/query-engine/filtering/) |

### 例子 {#example-5}

🌐 Example

```js
const entry = await strapi.db.query('api::blog.article').delete({
  where: { id: 1 },
});
```