From 033e3a4e6fc94dd98cd23bcd7c0132aae5add927 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Noco=C5=84?= <mnocon@users.noreply.github.com>
Date: Thu, 5 Feb 2026 12:58:59 +0100
Subject: [PATCH] Added doc for IBX-10186

---
 .../back_office/back_office_configuration.md  | 26 ++++++++++++++++++-
 docs/release_notes/ibexa_dxp_v5.0.md          |  9 +++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/administration/back_office/back_office_configuration.md b/docs/administration/back_office/back_office_configuration.md
index 87ad8601ee..d91c3e5c81 100644
--- a/docs/administration/back_office/back_office_configuration.md
+++ b/docs/administration/back_office/back_office_configuration.md
@@ -40,7 +40,9 @@ ibexa:
                     catalogs_limit: 10
 ```
 
-## Copy subtree limit
+## Subtree operations
+
+### Copy subtree limit
 
 Copying large subtrees can cause performance issues, so you can limit the number of content items that can be copied at once by setting the `ibexa.system.<scope>.subtree_operations.copy_subtree.limit` [configuration key](configuration.md#configuration-files).
 
@@ -48,6 +50,28 @@ The default value is `100`. You can set it to `-1` for no limit, or to `0` to co
 
 You can copy a subtree by calling the following command in CLI: `bin/console ibexa:copy-subtree <sourceLocationId> <targetLocationId>`.
 
+### Query subtree limit
+
+When working with large content trees, counting child items or calculating subtree sizes can cause significant performance degradation due to unbounded database queries. 
+You can limit these count operations by setting the `ibexa.system.<scope>.subtree_operations.query_subtree.limit` [configuration key](configuration.md#configuration-files):
+
+``` yaml
+ibexa:
+    system:
+        <scope>:
+            subtree_operations:
+                copy_subtree:
+                    limit: 100
+                query_subtree:
+                    limit: 500
+```
+
+The default value for `query_subtree.limit` is `500`.
+You can set it to `-1` to disable the limit.
+
+This limit is applied when the back office needs to determine if a location has children or calculate the number of items in a subtree.
+Instead of performing a full count, the query stops after finding the specified number of items, which significantly improves performance on locations with large numbers of children.
+
 ## Default locations
 
 Default location IDs for [content structure, Media, and users](locations.md#top-level-locations) in the menu are configured with the `ibexa.system.<scope>.location_ids` [configuration key](configuration.md#configuration-files):
diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md
index 074b312180..28dcc1eeb1 100644
--- a/docs/release_notes/ibexa_dxp_v5.0.md
+++ b/docs/release_notes/ibexa_dxp_v5.0.md
@@ -10,6 +10,15 @@ month_change: false
 
 <div class="release-notes" markdown="1">
 
+<!--DRAFT for v5.0.6 release -->
+#### Query subtree limit configuration
+
+A new `query_subtree.limit` configuration option improves performance when working with large content trees by limiting count operations.
+This prevents performance degradation from database queries when determining if locations have children or calculating subtree sizes.
+
+For more information, see [Subtree operations configuration](back_office_configuration.md#subtree-operations).
+
+
 [[% set version = 'v5.0.5' %]]
 
 [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]]