import DeepFilteringBlogLink from '/docs/snippets/deep-filtering-blog.md'

Document Service API: Filters#

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

Attribute operators#

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

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

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

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

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

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

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

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

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

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

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

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

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

<Endpoint
id="between"
kind="js"
path="strapi.documents().findMany()"
title="$between"
description={<>Attribute is between the 2 input values, boundaries included (e.g., $between[1, 3] will also return 1 and 3).</>}>

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

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

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

<Endpoint
id="containsi"
kind="js"
path="strapi.documents().findMany()"
title="$containsi"
description={<>$containsi is not case-sensitive, while $contains is.</>}>

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

<Endpoint
id="notcontainsi"
kind="js"
path="strapi.documents().findMany()"
title="$notContainsi"
description={<>$notContainsi is not case-sensitive, while $notContains is.</>}>

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

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

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

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

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

<Endpoint
id="null"
kind="js"
path="strapi.documents().findMany()"
title="$null"
description={<>Attribute is null.</>}>

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

<Endpoint
id="notnull"
kind="js"
path="strapi.documents().findMany()"
title="$notNull"
description={<>Attribute is not null.</>}>

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

Logical operators#

<Endpoint
id="and"
kind="js"
path="strapi.documents().findMany()"
title="$and"
description={<>All nested conditions must be true.</>}>

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

// $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' },
  },
});

<Endpoint
id="or"
kind="js"
path="strapi.documents().findMany()"
title="$or"
description={<>One or many nested conditions must be true.</>}>

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

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