# 使用查询引擎 API 进行过滤

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

🌐 Filtering with the Query Engine API

查询引擎 API 使用 `where` 参数结合逻辑运算符（`$and`、`$or`、`$not`）以及以 `$` 为前缀的属性运算符（比较、字符串匹配、范围）来过滤查询结果。

🌐 The Query Engine API filters query results using the `where` parameter with logical operators (`$and`, `$or`, `$not`) and attribute operators (comparison, string matching, range) prefixed with `$`.

:::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)。

:::

[查询引擎 API](/cms/api/query-engine/) 提供了使用其 [findMany()](/cms/api/query-engine/single-operations#findmany) 方法过滤结果的功能。

🌐 The [Query Engine API](/cms/api/query-engine/) offers the ability to filter results found with its [findMany()](/cms/api/query-engine/single-operations#findmany) method.

结果通过 `where` 参数进行过滤，该参数接受 [逻辑运算符](#logical-operators) 和 [属性运算符](#attribute-operators)。每个运算符都应以 `$` 为前缀。

🌐 Results are filtered with the `where` parameter that accepts [logical operators](#logical-operators) and [attribute operators](#attribute-operators). Every operator should be prefixed with `$`.

:::strapi Deep filtering with the various APIs

有关如何使用各种 API 进行深度过滤的示例，请参阅 [this blog article](https://strapi.io/blog/deep-filtering-alpha-26)。

:::

## 逻辑运算符 {#logical-operators}

🌐 Logical operators

### `$and`

所有嵌套条件必须是 `true`。

🌐 All nested conditions must be `true`.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    $and: [
      {
        title: 'Hello World',
      },
      {
        createdAt: { $gt: '2021-11-17T14:28:25.843Z' },
      },
    ],
  },
});
```

在传递具有嵌套条件的对象时，会隐式使用 `$and`：

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: 'Hello World',
    createdAt: { $gt: '2021-11-17T14:28:25.843Z' },
  },
});
```

### `$or`

一个或多个嵌套条件必须是 `true`。

🌐 One or many nested conditions must be `true`.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    $or: [
      {
        title: 'Hello World',
      },
      {
        createdAt: { $gt: '2021-11-17T14:28:25.843Z' },
      },
    ],
  },
});
```

### `$not`

否定嵌套条件。

🌐 Negates the nested conditions.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    $not: {
      title: 'Hello World',
    },
  },
});
```

:::note

`$not` 可以使用：

- 作为逻辑运算符（例如在 `where: { $not: { // conditions… }}` 中）
- 或 [作为属性运算符](#not-1)（例如在 `where: { attribute-name: $not: { … } }` 中）。

:::

:::tip

`$and`、`$or` 和 `$not` 操作符可以嵌套在另一个 `$and`、`$or` 或 `$not` 操作符中。

:::

## 属性运算符 {#attribute-operators}

🌐 Attribute Operators

:::caution

根据数据库的实现，使用这些运算符可能会给出不同的结果，因为比较是由数据库而不是 Strapi 处理的。

🌐 Using these operators may give different results depending on the database's implementation, as the comparison is handled by the database and not by Strapi.

:::

### `$not`

否定嵌套条件。

🌐 Negates nested condition(s).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $not: {
        $contains: 'Hello World',
      },
    },
  },
});
```

### `$eq`

属性等于输入值。

🌐 Attribute equals input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $eq: 'Hello World',
    },
  },
});
```

`$eq`可以省略：

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: 'Hello World',
  },
});
```

### `$eqi`

属性等于输入值（不区分大小写）。

🌐 Attribute equals input value (case-insensitive).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $eqi: 'HELLO World',
    },
  },
});
```

### `$ne`

属性不等于输入值。

🌐 Attribute does not equal input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $ne: 'ABCD',
    },
  },
});
```

### `$nei`

属性不等于输入值（不区分大小写）。

🌐 Attribute does not equal input value (case-insensitive).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $nei: 'abcd',
    },
  },
});
```

### `$in`

属性包含在输入列表中。

🌐 Attribute is contained in the input list.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $in: ['Hello', 'Hola', 'Bonjour'],
    },
  },
});
```

在传递一个值数组时可以省略 `$in`：

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: ['Hello', 'Hola', 'Bonjour'],
  },
});
```

### `$notIn`

输入列表中不包含属性。

🌐 Attribute is not contained in the input list.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $notIn: ['Hello', 'Hola', 'Bonjour'],
    },
  },
});
```

### `$lt`

属性小于输入值。

🌐 Attribute is less than the input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    rating: {
      $lt: 10,
    },
  },
});
```

### `$lte`

属性小于或等于输入值。

🌐 Attribute is less than or equal to the input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    rating: {
      $lte: 10,
    },
  },
});
```

### `$gt`

属性大于输入值。

🌐 Attribute is greater than the input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    rating: {
      $gt: 5,
    },
  },
});
```

### `$gte`

属性大于或等于输入值。

🌐 Attribute is greater than or equal to the input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    rating: {
      $gte: 5,
    },
  },
});
```

### `$between`

属性介于两个输入值之间，包括边界（例如，`$between[1, 3]` 也会返回 `1` 和 `3`）。

🌐 Attribute is between the 2 input values, boundaries included (e.g., `$between[1, 3]` will also return `1` and `3`).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    rating: {
      $between: [1, 20],
    },
  },
});
```

### `$contains`

属性包含输入值（区分大小写）。

🌐 Attribute contains the input value (case-sensitive).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $contains: 'Hello',
    },
  },
});
```

### `$notContains`

属性不包含输入值（区分大小写）。

🌐 Attribute does not contain the input value (case-sensitive).

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $notContains: 'Hello',
    },
  },
});
```

### `$containsi`

属性包含输入值。`$containsi`不区分大小写，而[$contains](#contains)区分大小写。

🌐 Attribute contains the input value. `$containsi` is not case-sensitive, while [$contains](#contains) is.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $containsi: 'hello',
    },
  },
});
```

### `$notContainsi`

属性不包含输入值。`$notContainsi` 不区分大小写，而 [$notContains](#notcontains) 区分大小写。

🌐 Attribute does not contain the input value. `$notContainsi` is not case-sensitive, while [$notContains](#notcontains) is.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $notContainsi: 'hello',
    },
  },
});
```

### `$startsWith`

属性以输入值开始。

🌐 Attribute starts with input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $startsWith: 'ABCD',
    },
  },
});
```

### `$endsWith`

属性以输入值结尾。

🌐 Attribute ends with input value.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $endsWith: 'ABCD',
    },
  },
});
```

### `$null`

属性是 `null`。

🌐 Attribute is `null`.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $null: true,
    },
  },
});
```

### `$notNull`

属性不是 `null`。

🌐 Attribute is not `null`.

**示例**

```js
const entries = await strapi.db.query('api::article.article').findMany({
  where: {
    title: {
      $notNull: true,
    },
  },
});
```