Document Service API: Filters

Page summary:

The Document Service API provides attribute operators ($eq, $lt, $contains, etc.) and logical operators ($and, $or, $not) to filter query results with support for case-sensitive and case-insensitive matching.

The Document Service API offers the ability to filter results.

The following operators are available:

Operator	Description
$eq	Equal
$eqi	Equal (case-insensitive)
$ne	Not equal
$nei	Not equal (case-insensitive)
$lt	Less than
$lte	Less than or equal to
$gt	Greater than
$gte	Greater than or equal to
$in	Included in an array
$notIn	Not included in an array
$contains	Contains
$notContains	Does not contain
$containsi	Contains (case-insensitive)
$notContainsi	Does not contain (case-insensitive)
$null	Is null
$notNull	Is not null
$between	Is between
$startsWith	Starts with
$startsWithi	Starts with (case-insensitive)
$endsWith	Ends with
$endsWithi	Ends with (case-insensitive)
$or	Joins the filters in an "or" expression
$and	Joins the filters in an "and" expression
$not	Joins the filters in an "not" expression

Filter values are cast to the type of the filtered attribute. A value that cannot be cast throws a ValidationError (e.g., 'no' on a boolean attribute, or 'tomorrow' on a date attribute). For boolean attributes, the accepted values are listed in the REST API filters documentation.

Deep filtering with the various APIs

For examples of how to deep filter with the various APIs, please refer to this blog article.

Attribute operators

strapi.documents().findMany()

$not

Negates the nested condition(s).

JavaScript

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

strapi.documents().findMany()

$eq

Attribute equals input value.

JavaScript

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

Shorthand

// $eq can be omitted:
const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    title: 'Hello World',
  },
});

strapi.documents().findMany()

$eqi

Attribute equals input value (case-insensitive).

JavaScript

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

strapi.documents().findMany()

$ne

Attribute does not equal input value.

JavaScript

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

strapi.documents().findMany()

$nei

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

JavaScript

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

strapi.documents().findMany()

$in

Attribute is contained in the input list.

JavaScript

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

Shorthand

// $in can be omitted when passing an array of values:
const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    title: ['Hello', 'Hola', 'Bonjour'],
  },
});

strapi.documents().findMany()

$notIn

Attribute is not contained in the input list.

JavaScript

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

strapi.documents().findMany()

$lt

Attribute is less than the input value.

JavaScript

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

strapi.documents().findMany()

$lte

Attribute is less than or equal to the input value.

JavaScript

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

strapi.documents().findMany()

$gt

Attribute is greater than the input value.

JavaScript

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

strapi.documents().findMany()

$gte

Attribute is greater than or equal to the input value.

JavaScript

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

strapi.documents().findMany()

$between

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

JavaScript

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

strapi.documents().findMany()

$contains

Attribute contains the input value (case-sensitive).

JavaScript

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

strapi.documents().findMany()

$notContains

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

JavaScript

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

strapi.documents().findMany()

$containsi

$containsi is not case-sensitive, while $contains is.

JavaScript

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

strapi.documents().findMany()

$notContainsi

$notContainsi is not case-sensitive, while $notContains is.

JavaScript

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

strapi.documents().findMany()

$startsWith

Attribute starts with input value (case-sensitive).

JavaScript

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

strapi.documents().findMany()

$startsWithi

Attribute starts with input value (case-insensitive).

JavaScript

const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    title: {
      $startsWithi: 'ABCD', // will return the same as filtering with 'abcd'
    },
  },
});

strapi.documents().findMany()

$endsWith

Attribute ends with input value (case-sensitive).

JavaScript

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

strapi.documents().findMany()

$endsWithi

Attribute ends with input value (case-insensitive).

JavaScript

const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    title: {
      $endsWith: 'ABCD', // will return the same as filtering with 'abcd'
    },
  },
});

strapi.documents().findMany()

$null

Attribute is null. Use true or false: $null: false is equivalent to $notNull: true.

JavaScript

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

strapi.documents().findMany()

$notNull

Attribute is not null. Use true or false: $notNull: false is equivalent to $null: true.

JavaScript

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

Logical operators

strapi.documents().findMany()

$and

All nested conditions must be true.

JavaScript

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

Implicit $and

// $and will be used implicitly when passing an object with nested conditions:
const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    title: 'Hello World',
    createdAt: { $gt: '2021-11-17T14:28:25.843Z' },
  },
});

strapi.documents().findMany()

$or

One or many nested conditions must be true.

JavaScript

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

strapi.documents().findMany()

$not

Negates the nested conditions.

JavaScript

const entries = await strapi.documents('api::article.article').findMany({
  filters: {
    $not: {
      title: 'Hello World',
    },
  },
});

Note

$not can be used as:

• a logical operator (e.g. in filters: { $not: { // conditions... }})
• an attribute operator (e.g. in filters: { attribute-name: $not: { ... } }).

Tip

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