From d7d45ac8596edb79e7aaf10c2530aba0b88d35f7 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 16 Jun 2022 18:37:47 +0200 Subject: [PATCH] Explain Entity Service vs. Query Engine + document knex access --- .../database-apis-reference/entity-service-api.md | 4 ++++ .../database-apis-reference/query-engine-api.md | 6 ++++-- .../snippets/entity-query-knex-callout.md | 5 +++++ 3 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md index 7dd79b5b66..507509b43b 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md @@ -8,6 +8,10 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d Strapi provides an Entity Service API, built on top of the [Query Engine API](/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md). The Entity Service is the layer that handles Strapi's complex data structures like [components](/developer-docs/latest/development/backend-customization/models.md#components) and [dynamic zones](/developer-docs/latest/development/backend-customization/models.md#dynamic-zones), and uses the Query Engine API under the hood to execute database queries. +::: strapi Entity Service API vs. Query Engine API +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md)!!! +::: + ## Basic usage The Entity Service is available through `strapi.entityService`: diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md index 44ff4cee2a..aae9d8f8cd 100644 --- a/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/query-engine-api.md @@ -6,9 +6,11 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/d # Query Engine API -Strapi provides a Query Engine API to interact with the database layer at a lower level. It should mostly be used by plugin developers and developers adding custom business logic to their applications. +Strapi provides a Query Engine API to interact with the database layer at a lower level. It 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 [Entity Service API](/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md) instead. -Strapi's Query Engine API gives unrestricted internal access to the database layer. It is not aware of the complex data structures like components and dynamic zones, as opposed to the [Entity Service API](/developer-docs/latest/developer-resources/database-apis-reference/entity-service-api.md). +::: strapi Entity Service API vs. Query Engine API +!!!include(developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md)!!! +::: ## Basic usage diff --git a/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md b/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md new file mode 100644 index 0000000000..db792261c3 --- /dev/null +++ b/docs/developer-docs/latest/developer-resources/database-apis-reference/snippets/entity-query-knex-callout.md @@ -0,0 +1,5 @@ +Strapi v4 offers several layers to interact with the backend and build your queries: + +* The Entity Service API is the recommended API to interact with the Strapi backend. The Entity Service is the layer that handles Strapi's 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 Entity Service API does not cover your use case. +* If you need direct access to `knex` functions, use `strapi.db.connection`.