Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

使用查询引擎 API 进行过滤

🌐 Filtering with the Query Engine API

Caution

在大多数情况下，你不应该使用查询引擎 API，而应使用 文档服务 API。

🌐 In most cases you should not use the Query Engine API and rather use the Document Service API.

仅当你确切知道自己在做什么时才使用查询引擎 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:

查询引擎 API 提供了使用其 findMany() 方法过滤结果的功能。

🌐 The Query Engine API offers the ability to filter results found with its findMany() method.

结果通过 where 参数进行过滤，该参数接受 逻辑运算符 和 属性运算符。每个运算符都应以 $ 为前缀。

🌐 Results are filtered with the where parameter that accepts logical operators and attribute operators. Every operator should be prefixed with $.

Deep filtering with the various APIs

有关如何使用各种 API 进行深度过滤的示例，请参阅 this blog article。

逻辑运算符​

🌐 Logical operators

$and​

所有嵌套条件必须是 true。

🌐 All nested conditions must be true.

示例

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

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

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.

示例

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.

示例

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

$not 可以使用：

  • 作为逻辑运算符（例如在 where: { $not: { // conditions… }} 中）
  • 或 作为属性运算符（例如在 where: { attribute-name: $not: { … } } 中）。
Tip

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

属性运算符​

🌐 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).

示例

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

$eq​

属性等于输入值。

🌐 Attribute equals input value.

示例

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

$eq可以省略：

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

$eqi​

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

🌐 Attribute equals input value (case-insensitive).

示例

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

$ne​

属性不等于输入值。

🌐 Attribute does not equal input value.

示例

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

$nei​

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

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

示例

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

$in​

属性包含在输入列表中。

🌐 Attribute is contained in the input list.

示例

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

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

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

$notIn​

输入列表中不包含属性。

🌐 Attribute is not contained in the input list.

示例

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

$lt​

属性小于输入值。

🌐 Attribute is less than the input value.

示例

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.

示例

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

$gt​

属性大于输入值。

🌐 Attribute is greater than the input value.

示例

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.

示例

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).

示例

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

$contains​

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

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

示例

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

$notContains​

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

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

示例

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

$containsi​

属性包含输入值。$containsi不区分大小写，而$contains区分大小写。

🌐 Attribute contains the input value. $containsi is not case-sensitive, while $contains is.

示例

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

$notContainsi​

属性不包含输入值。$notContainsi 不区分大小写，而 $notContains 区分大小写。

🌐 Attribute does not contain the input value. $notContainsi is not case-sensitive, while $notContains is.

示例

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

$startsWith​

属性以输入值开始。

🌐 Attribute starts with input value.

示例

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

$endsWith​

属性以输入值结尾。

🌐 Attribute ends with input value.

示例

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

$null​

属性是 null。

🌐 Attribute is null.

示例

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

$notNull​

属性不是 null。

🌐 Attribute is not null.

示例

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