使用查询引擎 API 进行过滤

页面摘要： 查询引擎 API 通过 where 参数对查询结果进行过滤，该参数接受以 $ 为前缀的逻辑运算符（$and、$or、$not）与属性运算符（比较、字符串匹配、范围等）。

WARNING

大多数情况下你不应使用 Query Engine API，而应使用 Document Service API。

只有当你能确定自己在做什么时才使用 Query Engine API，例如需要直接与数据库唯一行交互的底层 API。

请注意，Query Engine API 无法感知 Strapi 5 的高级功能，如草稿与发布、国际化、内容历史等。这也意味着 Query Engine API 无法使用 documentId，而会使用 id，这可能导致数据库层面的意外后果，或与 Strapi 5 功能出现部分或不完整的兼容性问题。

WARNING

在深入阅读 Query Engine API 文档之前，建议你先阅读以下介绍：

查询引擎 API 提供了对通过 findMany() 方法获取的结果进行过滤的能力。

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

使用各类 API 进行深度过滤

如需各类 API 深度过滤的示例，请参阅这篇博客文章。

逻辑运算符（Logical operators）

$and

所有嵌套条件都必须为 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 即可。

示例

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

$not

对嵌套条件取反。

示例

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）

WARNING

使用这些运算符时，由于比较由数据库而非 Strapi 处理，结果可能因数据库实现不同而有所差异。

$not

对嵌套条件取反。

示例

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

$eq

属性等于输入值。

示例

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

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

示例

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

$ne

属性不等于输入值。

示例

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

$nei

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

示例

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

$in

属性包含于输入列表中。

示例

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

属性不包含于输入列表中。

示例

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

$lt

属性小于输入值。

示例

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

$lte

属性小于或等于输入值。

示例

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

$gt

属性大于输入值。

示例

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

$gte

属性大于或等于输入值。

示例

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

$between

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

示例

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

$contains

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

示例

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

$notContains

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

示例

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

$containsi

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

示例

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

$notContainsi

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

示例

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

$startsWith

属性以输入值开头。

示例

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

$endsWith

属性以输入值结尾。

示例

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

$null

属性为 null。

示例

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

$notNull

属性不为 null。

示例

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