Skip to main content

Query Engine API

🏗 Work in progress

The content of this page might not be fully up-to-date with Strapi 5 yet.

☑️ Prerequisites

Before diving deeper into the Query Engine API documentation, it is recommended that you read the following introductions:

The Strapi backend provides a Query Engine API to interact with the database layer at a lower level. The Query Engine API should mostly be used by plugin developers and developers adding custom business logic to their applications.

👉 In most use cases, it's recommended to use the Document Service API instead of the Query Engine API.

🤓 Document Service API vs. Query Engine API

Strapi v4 offers several layers to interact with the backend and build your queries:

  • The Document Service API is the recommended API to interact with your application's database. The Document Service is the layer that handles Strapi's document model and the complex data structures like components and dynamic zones, which the lower-level layers are not aware of.
  • The Query Engine API interacts with the database layer at a lower level and is used under the hood to execute database queries. It gives unrestricted internal access to the database layer, but should be used only if the Document Service API does not cover your use case.
  • If you need direct access to knex functions, use strapi.db.connection.

Basic usage​

The Query Engine is available through strapi.db.query:

strapi.db.query('api::blog.article').findMany({ // uid syntax: 'api::api-name.content-type-name'
  where: {
    title: {
      $startsWith: '2021',
      $endsWith: 'v4',
    },
  },
  populate: {
    category: true,
  },
});

Available operations​

The Query Engine allows the following operations on database entries: