Skip to main content

Filtering with the Query Engine API

βœ‹ Caution

In most cases you should not use the Query Engine API and rather use the Document Service 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.

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.

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

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

Logical operators​

$and​

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 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​

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',
},
},
});
✏️ Note

$not can be used:

  • as a logical operator (e.g. in where: { $not: { // conditions… }})
  • or as an attribute operator (e.g. in where: { attribute-name: $not: { … } }).
πŸ’‘ Tip

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

Attribute Operators​

βœ‹ Caution

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 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 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​

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​

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​

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​

Attribute is null.

Example

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

$notNull​

Attribute is not null.

Example

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