Skip to main content

Document Service API: Filters

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

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

GETstrapi.documents().findMany()

Negates the nested condition(s).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute equals input value.

JavaScriptShorthand

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute equals input value (case-insensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute does not equal input value.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is contained in the input list.

JavaScriptShorthand

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is not contained in the input list.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is less than the input value.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is less than or equal to the input value.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is greater than the input value.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is greater than or equal to the input value.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute contains the input value (case-sensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute starts with input value (case-sensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute starts with input value (case-insensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute ends with input value (case-sensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute ends with input value (case-insensitive).

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is null.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Attribute is not null.

GETstrapi.documents().findMany()

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

Logical operators

GETstrapi.documents().findMany()

All nested conditions must be true.

JavaScriptImplicit $and

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

One or many nested conditions must be true.

GETstrapi.documents().findMany()

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

GETstrapi.documents().findMany()

Negates the nested conditions.

GETstrapi.documents().findMany()

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.

On this page

Attribute operators
Logical operators

Contribute to this page