使用查询引擎 API 进行过滤

¥Filtering with the Query Engine API

✋ 提醒

在大多数情况下，你不应使用查询引擎 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 功能，如草稿和发布、国际化、内容历史记录等。

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

查询引擎 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 $.

逻辑运算符

¥Logical operators

$and

所有嵌套条件必须为 true。

¥All nested conditions must be true.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    $and: [
      {
        title: 'Hello World',
      },
      {
        createdAt: { $gt: '2021-11-17T14:28:25.843Z' },
      },
    ],
  },
});

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

¥$and is used implicitly when passing an object with nested conditions:

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.

示例

¥Example

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.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    $not: {
      title: 'Hello World',
    },
  },
});

✏️ 注意

$not 可用于：

¥$not can be used:

• 作为逻辑运算符（例如在 where: { $not: { // conditions… }} 中）

  ¥as a logical operator (e.g. in where: { $not: { // conditions… }})

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

  ¥or as an attribute operator (e.g. in where: { attribute-name: $not: { … } }).

💡 提示

$and、$or 和 $not 运算符可嵌套在另一个 $and、$or 或 $not 运算符内。

¥$and, $or and $not operators are nestable inside of another $and, $or or $not operator.

属性运算符

¥Attribute Operators

✋ 提醒

根据数据库的实现，使用这些运算符可能会给出不同的结果，因为比较是由数据库而不是 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).

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $not: {
        $contains: 'Hello World',
      },
    },
  },
});

$eq

属性等于输入值。

¥Attribute equals input value.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $eq: 'Hello World',
    },
  },
});

$eq 可以省略：

¥$eq can be omitted:

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: 'Hello World',
  },
});

$eqi

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

¥Attribute equals input value (case-insensitive).

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $eqi: 'HELLO World',
    },
  },
});

$ne

属性不等于输入值。

¥Attribute does not equal input value.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $ne: 'ABCD',
    },
  },
});

$nei

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

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

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $nei: 'abcd',
    },
  },
});

$in

属性包含在输入列表中。

¥Attribute is contained in the input list.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $in: ['Hello', 'Hola', 'Bonjour'],
    },
  },
});

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

¥$in can be omitted when passing an array of values:

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: ['Hello', 'Hola', 'Bonjour'],
  },
});

$notIn

输入列表中不包含属性。

¥Attribute is not contained in the input list.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $notIn: ['Hello', 'Hola', 'Bonjour'],
    },
  },
});

$lt

属性小于输入值。

¥Attribute is less than the input value.

示例

¥Example

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.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    rating: {
      $lte: 10,
    },
  },
});

$gt

属性大于输入值。

¥Attribute is greater than the input value.

示例

¥Example

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.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    rating: {
      $gte: 5,
    },
  },
});

$between

属性位于 2 个输入值之间，包括边界（例如，$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).

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    rating: {
      $between: [1, 20],
    },
  },
});

$contains

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

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

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $contains: 'Hello',
    },
  },
});

$notContains

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

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

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $notContains: 'Hello',
    },
  },
});

$containsi

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

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

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $containsi: 'hello',
    },
  },
});

$notContainsi

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

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

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $notContainsi: 'hello',
    },
  },
});

$startsWith

属性以输入值开始。

¥Attribute starts with input value.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $startsWith: 'ABCD',
    },
  },
});

$endsWith

属性以输入值结尾。

¥Attribute ends with input value.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $endsWith: 'ABCD',
    },
  },
});

$null

属性为 null。

¥Attribute is null.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $null: true,
    },
  },
});

$notNull

属性不是 null。

¥Attribute is not null.

示例

¥Example

const entries = await strapi.db.query('api::article.article').findMany({


  where: {
    title: {
      $notNull: true,
    },
  },
});