From a6c5526ab516ec84410fc889667b5716e5bc94f9 Mon Sep 17 00:00:00 2001
From: Morten Svanaes <netroms@gmail.com>
Date: Tue, 1 Sep 2026 01:04:07 +0800
Subject: [PATCH] perf: Bulk load option set options and restore entity cache
 [DHIS2-21905]

Nested options on /api/optionSets loaded one collection per option set, and
query-cache hits re-selected every OptionSet row because the entity-level cache
was lost in the OptionSet.hbm.xml to JPA migration.

- Restore the OptionSet entity L2 cache with an explicit ehcache region
- Preload requested options collections with one cache-aware fetch-join query
- Skip the preload entirely when the requested fields omit options
---
 .../org/hisp/dhis/option/OptionService.java   |   9 +
 .../java/org/hisp/dhis/option/OptionSet.java  |   1 +
 .../org/hisp/dhis/option/OptionSetStore.java  |  51 ++++
 .../org/hisp/dhis/config/StoreConfig.java     |   7 -
 .../dhis/option/DefaultOptionService.java     |  11 +-
 .../hibernate/HibernateOptionSetStore.java    |  97 +++++++
 .../src/main/resources/ehcache.xml            |   7 +
 .../cache/HibernateEhcacheConfigFileTest.java |  12 +
 .../dhis/cache/HibernateQueryCacheTest.java   |  37 ++-
 .../OptionSetControllerQueryCountTest.java    | 247 ++++++++++++++++++
 .../option/OptionSetController.java           |  25 ++
 11 files changed, 491 insertions(+), 13 deletions(-)
 create mode 100644 dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSetStore.java
 create mode 100644 dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/hibernate/HibernateOptionSetStore.java
 create mode 100644 dhis-2/dhis-test-web-api/src/test/java/org/hisp/dhis/webapi/controller/option/OptionSetControllerQueryCountTest.java

diff --git a/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionService.java b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionService.java
index 9d94d7840e2f..98922c05315c 100644
--- a/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionService.java
+++ b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionService.java
@@ -65,6 +65,15 @@ public interface OptionService {
 
   List<OptionSet> getAllOptionSets();
 
+  /**
+   * Initializes the {@link OptionSet#getOptions()} collections of the supplied managed option sets.
+   * Collections missing from the second-level cache are loaded together with one bulk query;
+   * collections present in the cache are initialized from it without SQL.
+   *
+   * @param optionSets managed option sets whose options collections should be initialized
+   */
+  void preloadOptions(@Nonnull Collection<OptionSet> optionSets);
+
   List<Option> findOptionsByNamePattern(
       @Nonnull String optionSet, @CheckForNull String infix, @CheckForNull Integer maxResults);
 
diff --git a/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSet.java b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSet.java
index 828d2909d789..fce035694de3 100644
--- a/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSet.java
+++ b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSet.java
@@ -100,6 +100,7 @@
 @Setter
 @Entity
 @Table(name = "optionset")
+@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
 public class OptionSet extends BaseMetadataObject implements IdentifiableObject, VersionedObject {
 
   @Id
diff --git a/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSetStore.java b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSetStore.java
new file mode 100644
index 000000000000..47b174265a74
--- /dev/null
+++ b/dhis-2/dhis-api/src/main/java/org/hisp/dhis/option/OptionSetStore.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2004-2026, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.option;
+
+import java.util.Collection;
+import javax.annotation.Nonnull;
+import org.hisp.dhis.common.IdentifiableObjectStore;
+
+/**
+ * Persistence operations specific to {@link OptionSet}.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
+public interface OptionSetStore extends IdentifiableObjectStore<OptionSet> {
+
+  /**
+   * Initializes the {@link OptionSet#getOptions()} collections of the supplied managed option sets.
+   * Collections missing from the second-level cache are loaded together with one bulk query;
+   * collections present in the cache are initialized from it without SQL.
+   *
+   * @param optionSets managed option sets whose options collections should be initialized
+   */
+  void preloadOptions(@Nonnull Collection<OptionSet> optionSets);
+}
diff --git a/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/config/StoreConfig.java b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/config/StoreConfig.java
index acadf381c48d..72faada96b8c 100644
--- a/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/config/StoreConfig.java
+++ b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/config/StoreConfig.java
@@ -44,7 +44,6 @@
 import org.hisp.dhis.indicator.IndicatorGroupSet;
 import org.hisp.dhis.indicator.IndicatorType;
 import org.hisp.dhis.legend.LegendSet;
-import org.hisp.dhis.option.OptionSet;
 import org.hisp.dhis.predictor.PredictorGroup;
 import org.hisp.dhis.program.ProgramExpression;
 import org.hisp.dhis.program.ProgramIndicatorGroup;
@@ -124,12 +123,6 @@ public HibernateIdentifiableObjectStore<Constant> constantStore() {
         entityManager, jdbcTemplate, publisher, Constant.class, aclService, true);
   }
 
-  @Bean("org.hisp.dhis.option.OptionSetStore")
-  public HibernateIdentifiableObjectStore<OptionSet> optionSetStore() {
-    return new HibernateIdentifiableObjectStore<>(
-        entityManager, jdbcTemplate, publisher, OptionSet.class, aclService, true);
-  }
-
   @Bean("org.hisp.dhis.legend.LegendSetStore")
   public HibernateIdentifiableObjectStore<LegendSet> legendSetStore() {
     return new HibernateIdentifiableObjectStore<>(
diff --git a/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/DefaultOptionService.java b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/DefaultOptionService.java
index c90a660bcda5..0f68fb16619e 100644
--- a/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/DefaultOptionService.java
+++ b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/DefaultOptionService.java
@@ -35,12 +35,10 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 import lombok.RequiredArgsConstructor;
-import org.hisp.dhis.common.IdentifiableObjectStore;
 import org.hisp.dhis.common.UID;
 import org.hisp.dhis.common.ValueType;
 import org.hisp.dhis.feedback.ConflictException;
 import org.hisp.dhis.feedback.ErrorCode;
-import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -50,8 +48,7 @@
 @RequiredArgsConstructor
 @Service("org.hisp.dhis.option.OptionService")
 public class DefaultOptionService implements OptionService {
-  @Qualifier("org.hisp.dhis.option.OptionSetStore")
-  private final IdentifiableObjectStore<OptionSet> optionSetStore;
+  private final OptionSetStore optionSetStore;
 
   private final OptionStore optionStore;
 
@@ -132,6 +129,12 @@ public List<OptionSet> getAllOptionSets() {
     return optionSetStore.getAll();
   }
 
+  @Override
+  @Transactional(readOnly = true)
+  public void preloadOptions(@Nonnull Collection<OptionSet> optionSets) {
+    optionSetStore.preloadOptions(optionSets);
+  }
+
   // -------------------------------------------------------------------------
   // Option
   // -------------------------------------------------------------------------
diff --git a/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/hibernate/HibernateOptionSetStore.java b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/hibernate/HibernateOptionSetStore.java
new file mode 100644
index 000000000000..a5b4cd2817bb
--- /dev/null
+++ b/dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/option/hibernate/HibernateOptionSetStore.java
@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2004-2026, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.option.hibernate;
+
+import jakarta.persistence.EntityManager;
+import java.util.Collection;
+import java.util.List;
+import javax.annotation.Nonnull;
+import org.hibernate.Cache;
+import org.hibernate.Hibernate;
+import org.hisp.dhis.common.hibernate.HibernateIdentifiableObjectStore;
+import org.hisp.dhis.option.OptionSet;
+import org.hisp.dhis.option.OptionSetStore;
+import org.hisp.dhis.security.acl.AclService;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Repository;
+
+/**
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
+@Repository("org.hisp.dhis.option.OptionSetStore")
+public class HibernateOptionSetStore extends HibernateIdentifiableObjectStore<OptionSet>
+    implements OptionSetStore {
+
+  private static final String OPTIONS_COLLECTION_ROLE = OptionSet.class.getName() + ".options";
+
+  public HibernateOptionSetStore(
+      EntityManager entityManager,
+      JdbcTemplate jdbcTemplate,
+      ApplicationEventPublisher publisher,
+      AclService aclService) {
+    super(entityManager, jdbcTemplate, publisher, OptionSet.class, aclService, true);
+  }
+
+  @Override
+  public void preloadOptions(@Nonnull Collection<OptionSet> optionSets) {
+    if (optionSets.isEmpty()) {
+      return;
+    }
+
+    Cache cache = getSession().getSessionFactory().getCache();
+    List<OptionSet> missing =
+        optionSets.stream()
+            .filter(
+                optionSet -> !cache.containsCollection(OPTIONS_COLLECTION_ROLE, optionSet.getId()))
+            .toList();
+
+    if (!missing.isEmpty()) {
+      // One bulk fetch for every collection absent from the second-level cache. The query must not
+      // be cacheable: the Hibernate query cache stores entity identifiers only and cannot
+      // rematerialize join-fetched collection state, so caching it would recreate the per-owner
+      // load storm this method exists to remove.
+      getQuery(
+              """
+              select distinct optionSet from OptionSet optionSet
+              left join fetch optionSet.options
+              where optionSet in :optionSets
+              """,
+              OptionSet.class)
+          .setParameter("optionSets", missing)
+          .setCacheable(false)
+          .list();
+    }
+
+    // Initializes the remaining collections from the second-level cache (collection ids plus the
+    // Option entity region); collections loaded by the bulk fetch above are already initialized.
+    optionSets.forEach(optionSet -> Hibernate.initialize(optionSet.getOptions()));
+  }
+}
diff --git a/dhis-2/dhis-support/dhis-support-hibernate/src/main/resources/ehcache.xml b/dhis-2/dhis-support/dhis-support-hibernate/src/main/resources/ehcache.xml
index f05a53f5407c..5f5fc9c27620 100644
--- a/dhis-2/dhis-support/dhis-support-hibernate/src/main/resources/ehcache.xml
+++ b/dhis-2/dhis-support/dhis-support-hibernate/src/main/resources/ehcache.xml
@@ -124,6 +124,13 @@
     <expiry><ttl unit="seconds">3600</ttl></expiry>
     <resources><heap unit="entries">200000</heap></resources>
   </cache>
+  <!-- Entity-level cache restored after the OptionSet.hbm.xml -> JPA migration dropped it: the
+       metadata query cache stores OptionSet ids only, so without this region every query-cache
+       hit re-selects each OptionSet row by id (one select per option set in the result). -->
+  <cache alias="org.hisp.dhis.option.OptionSet">
+    <expiry><ttl unit="seconds">3600</ttl></expiry>
+    <resources><heap unit="entries">20000</heap></resources>
+  </cache>
   <cache alias="org.hisp.dhis.trackedentity.TrackedEntityAttribute">
     <expiry><ttl unit="seconds">3600</ttl></expiry>
     <resources><heap unit="entries">20000</heap></resources>
diff --git a/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateEhcacheConfigFileTest.java b/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateEhcacheConfigFileTest.java
index 27698435174f..89b36c3beede 100644
--- a/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateEhcacheConfigFileTest.java
+++ b/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateEhcacheConfigFileTest.java
@@ -49,6 +49,7 @@
 import org.hisp.dhis.attribute.Attribute;
 import org.hisp.dhis.cache.HibernateEhcacheConfigFileTest.DhisConfig;
 import org.hisp.dhis.external.conf.ConfigurationKey;
+import org.hisp.dhis.option.OptionSet;
 import org.hisp.dhis.test.config.PostgresTestConfigOverride;
 import org.hisp.dhis.test.integration.PostgresIntegrationTestBase;
 import org.hisp.dhis.user.User;
@@ -94,6 +95,13 @@ public PostgresTestConfigOverride postgresTestConfigOverride() {
    */
   private static final long EHCACHE_XML_USER_HEAP_ENTRIES = 100_000;
 
+  /**
+   * Heap bound declared explicitly for the {@code org.hisp.dhis.option.OptionSet} entity region in
+   * ehcache.xml. The entity-level cache was lost when OptionSet.hbm.xml was migrated to JPA
+   * annotations (commit fa6a8558f8c0); without it a query-cache hit reloads every OptionSet row.
+   */
+  private static final long EHCACHE_XML_OPTION_SET_HEAP_ENTRIES = 20_000;
+
   @Autowired private EntityManagerFactory entityManagerFactory;
 
   @Test
@@ -124,6 +132,10 @@ void regionsCarryTheEhcacheXmlHeapBounds() {
         EHCACHE_XML_USER_HEAP_ENTRIES,
         heapEntries(cacheManager, User.class.getName()),
         "explicitly declared entity regions must carry their own ehcache.xml heap bound");
+    assertEquals(
+        EHCACHE_XML_OPTION_SET_HEAP_ENTRIES,
+        heapEntries(cacheManager, OptionSet.class.getName()),
+        "OptionSet entity state must use its explicit store-by-reference region");
     assertEquals(
         EHCACHE_XML_TIMESTAMPS_HEAP_ENTRIES,
         heapEntries(cacheManager, "default-update-timestamps-region"),
diff --git a/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateQueryCacheTest.java b/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateQueryCacheTest.java
index abb68820ecee..cbf09e423a24 100644
--- a/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateQueryCacheTest.java
+++ b/dhis-2/dhis-test-integration/src/test/java/org/hisp/dhis/cache/HibernateQueryCacheTest.java
@@ -58,6 +58,13 @@
 @ContextConfiguration(classes = {DhisConfig.class})
 class HibernateQueryCacheTest extends PostgresIntegrationTestBase {
 
+  /**
+   * Dedicated query-cache region for this test. Must not equal the {@link OptionSet} entity region
+   * name ({@code org.hisp.dhis.option.OptionSet}), otherwise query results and entity state would
+   * share one JCache alias and the region statistics would mix both.
+   */
+  private static final String OPTION_SET_QUERY_REGION = OptionSet.class.getName() + ".query-test";
+
   static class DhisConfig {
     @Bean
     public PostgresTestConfigOverride postgresTestConfigOverride() {
@@ -129,11 +136,37 @@ void testHouseKeepingJobWithCache() {
         10,
         sessionFactory
             .getStatistics()
-            .getCacheRegionStatistics(OptionSet.class.getName())
+            .getCacheRegionStatistics(OPTION_SET_QUERY_REGION)
             .getHitCount());
     assertTrue(sessionFactory.getStatistics().getQueryCacheHitCount() > queryCacheHitCountBefore);
   }
 
+  @Test
+  @DisplayName(
+      "OptionSet query-cache hits resolve entity state from L2 across persistence contexts")
+  void queryCacheHitUsesOptionSetEntityCacheAcrossPersistenceContexts() {
+    setUpData();
+    sessionFactory.getCache().evictEntityData(OptionSet.class);
+    sessionFactory.getCache().evictQueryRegion(OPTION_SET_QUERY_REGION);
+    sessionFactory.getStatistics().clear();
+    entityManager.clear();
+
+    createSelectQuery(1);
+    entityManager.clear();
+    createSelectQuery(1);
+
+    Statistics statistics = sessionFactory.getStatistics();
+    assertEquals(1, statistics.getQueryCacheMissCount());
+    assertEquals(1, statistics.getQueryCacheHitCount());
+    assertEquals(
+        1,
+        statistics.getEntityLoadCount(),
+        "the query-cache hit must not reload OptionSet from PostgreSQL");
+    assertTrue(
+        statistics.getSecondLevelCacheHitCount() >= 1,
+        "the second persistence context must resolve OptionSet from entity L2");
+  }
+
   private void createSelectQuery(int numberOfQueries) {
     for (int i = 0; i < numberOfQueries; i++) {
       entityManager.getTransaction().begin();
@@ -147,7 +180,7 @@ private TypedQuery<OptionSet> createQuery(EntityManager entityManager) {
     return entityManager
         .createQuery("from OptionSet where code = :code", OptionSet.class)
         .setParameter("code", "OptionSetCodeA")
-        .setHint(QueryHints.HINT_CACHE_REGION, "org.hisp.dhis.option.OptionSet")
+        .setHint(QueryHints.HINT_CACHE_REGION, OPTION_SET_QUERY_REGION)
         .setHint(QueryHints.HINT_CACHEABLE, true);
   }
 }
diff --git a/dhis-2/dhis-test-web-api/src/test/java/org/hisp/dhis/webapi/controller/option/OptionSetControllerQueryCountTest.java b/dhis-2/dhis-test-web-api/src/test/java/org/hisp/dhis/webapi/controller/option/OptionSetControllerQueryCountTest.java
new file mode 100644
index 000000000000..ba7e92abe4ea
--- /dev/null
+++ b/dhis-2/dhis-test-web-api/src/test/java/org/hisp/dhis/webapi/controller/option/OptionSetControllerQueryCountTest.java
@@ -0,0 +1,247 @@
+/*
+ * Copyright (c) 2004-2026, University of Oslo
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.hisp.dhis.webapi.controller.option;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.persistence.EntityManagerFactory;
+import java.util.ArrayList;
+import java.util.List;
+import org.hibernate.SessionFactory;
+import org.hisp.dhis.common.ValueType;
+import org.hisp.dhis.http.HttpStatus;
+import org.hisp.dhis.jsontree.JsonList;
+import org.hisp.dhis.jsontree.JsonObject;
+import org.hisp.dhis.option.Option;
+import org.hisp.dhis.option.OptionSet;
+import org.hisp.dhis.test.config.QueryCountDataSourceProxy;
+import org.hisp.dhis.test.webapi.PostgresControllerIntegrationTestBase;
+import org.hisp.dhis.test.webapi.json.domain.JsonOptionSet;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.test.context.ContextConfiguration;
+
+/**
+ * Asserts the SQL shape of {@code /api/optionSets} when nested options are requested: the options
+ * collections of the selected page must be bulk-loaded in one statement instead of one lazy
+ * collection initialization per option set (DHIS2-21905).
+ *
+ * <p>Deliberately not {@code @Transactional}: fixtures are committed so requests observe real
+ * Hibernate second-level cache and invalidation behavior across commit boundaries. MockMvc tests
+ * share one thread-bound Hibernate session across requests, so between fixture setup and a measured
+ * request the persistence context is cleared explicitly; otherwise the list query would resolve the
+ * fixture instances from the first-level cache with their collections still initialized, and no
+ * option loading would be observable at all.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
+@ContextConfiguration(classes = QueryCountDataSourceProxy.class)
+class OptionSetControllerQueryCountTest extends PostgresControllerIntegrationTestBase {
+
+  private static final String OPTIONS_COLLECTION_REGION = OptionSet.class.getName() + ".options";
+
+  @Autowired private EntityManagerFactory entityManagerFactory;
+
+  /**
+   * Detaches everything from the thread-bound session so the next request loads fresh entities with
+   * uninitialized option collections. The flush inside {@code clearSession} requires an active
+   * transaction; flushing the clean read-only session is a no-op.
+   */
+  private void clearPersistenceContext() {
+    doInTransaction(dbmsManager::clearSession);
+  }
+
+  @Test
+  void nestedOptionsAreFetchedInOneQuery() {
+    List<String> uids = createOptionSetsWithOptions('A');
+    clearPersistenceContext();
+    evictOptionRegions();
+    QueryCountDataSourceProxy.clearCapturedSql();
+
+    JsonObject content = GET(nestedOptionsUrl(uids)).content(HttpStatus.OK);
+
+    assertOptionSetsWithOptions(content, uids.size());
+    assertEquals(
+        1,
+        QueryCountDataSourceProxy.countCapturedSqlMatching("optionvalue"),
+        "nested options must be fetched for all selected OptionSets in one SQL statement");
+  }
+
+  @Test
+  void warmNestedOptionsDoNotQueryOptionValue() {
+    List<String> uids = createOptionSetsWithOptions('F');
+    clearPersistenceContext();
+    evictOptionRegions();
+
+    // The first request fills the OptionSet entity, options collection, and Option entity regions.
+    String coldResponse = GET(nestedOptionsUrl(uids)).content(HttpStatus.OK).toJson();
+
+    // Clear only the persistence context and the SQL capture; the second-level cache stays warm.
+    clearPersistenceContext();
+    QueryCountDataSourceProxy.clearCapturedSql();
+
+    String warmResponse = GET(nestedOptionsUrl(uids)).content(HttpStatus.OK).toJson();
+
+    assertEquals(coldResponse, warmResponse, "warm response must equal the cold response");
+    assertEquals(
+        0,
+        QueryCountDataSourceProxy.countCapturedSqlMatching("optionvalue"),
+        "warm nested options must initialize from the second-level cache without SQL");
+  }
+
+  @Test
+  void fieldsWithoutOptionsDoNotLoadOptionValue() {
+    List<String> uids = createOptionSetsWithOptions('K');
+    clearPersistenceContext();
+    evictOptionRegions();
+    QueryCountDataSourceProxy.clearCapturedSql();
+
+    JsonObject content =
+        GET("/optionSets?filter=id:in:["
+                + String.join(",", uids)
+                + "]&fields=id,displayName&paging=false")
+            .content(HttpStatus.OK);
+
+    assertEquals(uids.size(), content.getList("optionSets", JsonOptionSet.class).size());
+    assertEquals(
+        0,
+        QueryCountDataSourceProxy.countCapturedSqlMatching("optionvalue"),
+        "requests without an options field must not load option data");
+  }
+
+  @Test
+  void updatedOptionNameAndCodeAreVisibleAfterCommit() {
+    List<String> uids = createOptionSetsWithOptions('P');
+    String url =
+        "/optionSets?filter=id:in:["
+            + String.join(",", uids)
+            + "]&fields=id,options[id,name,code]&paging=false";
+    clearPersistenceContext();
+    evictOptionRegions();
+    GET(url).content(HttpStatus.OK); // warm the option regions
+
+    String updatedSetUid = uids.get(0);
+    doInTransaction(
+        () -> {
+          OptionSet optionSet = manager.get(OptionSet.class, updatedSetUid);
+          Option option = optionSet.getOptions().get(0);
+          option.setName("OptionP1Renamed");
+          option.setCode("P1R");
+          manager.update(option);
+        });
+    clearPersistenceContext();
+
+    JsonObject content = GET(url).content(HttpStatus.OK);
+    JsonOptionSet updated = findOptionSet(content, updatedSetUid);
+    assertEquals("P1R", updated.getOptions().get(0).getCode());
+    assertEquals("OptionP1Renamed", updated.getOptions().get(0).getName());
+  }
+
+  @Test
+  void addedAndRemovedOptionsAreVisibleInOrderAfterCommit() {
+    List<String> uids = createOptionSetsWithOptions('U');
+    String url = nestedOptionsUrl(uids);
+    clearPersistenceContext();
+    evictOptionRegions();
+    GET(url).content(HttpStatus.OK); // warm the option regions
+
+    String updatedSetUid = uids.get(0);
+    doInTransaction(
+        () -> {
+          OptionSet optionSet = manager.get(OptionSet.class, updatedSetUid);
+          Option removed = optionSet.getOptions().get(0);
+          optionSet.getOptions().remove(removed);
+          manager.delete(removed);
+          Option added = createOption("U3");
+          added.setSortOrder(3);
+          added.setOptionSet(optionSet);
+          optionSet.addOption(added);
+          manager.save(added);
+          manager.update(optionSet);
+        });
+    clearPersistenceContext();
+
+    JsonObject content = GET(url).content(HttpStatus.OK);
+    JsonOptionSet updated = findOptionSet(content, updatedSetUid);
+    assertEquals(2, updated.getOptions().size(), "removed option must disappear, added one appear");
+    assertEquals("U2", updated.getOptions().get(0).getCode());
+    assertEquals("U3", updated.getOptions().get(1).getCode());
+  }
+
+  /**
+   * Creates five committed option sets of two options each, named from the given starting
+   * character, and returns their UIDs. Each test uses its own character range so names and codes
+   * stay unique in the shared database.
+   */
+  private List<String> createOptionSetsWithOptions(char startingCharacter) {
+    List<String> uids = new ArrayList<>();
+    doInTransaction(
+        () -> {
+          for (char c = startingCharacter; c < startingCharacter + 5; c++) {
+            Option first = createOption(c + "1");
+            first.setSortOrder(1);
+            Option second = createOption(c + "2");
+            second.setSortOrder(2);
+            OptionSet optionSet = createOptionSet(c, first, second);
+            optionSet.setValueType(ValueType.TEXT);
+            manager.save(optionSet);
+            uids.add(optionSet.getUid());
+          }
+        });
+    return uids;
+  }
+
+  private static String nestedOptionsUrl(List<String> uids) {
+    return "/optionSets?filter=id:in:["
+        + String.join(",", uids)
+        + "]&fields=id,options[id,code]&paging=false";
+  }
+
+  private static void assertOptionSetsWithOptions(JsonObject content, int expectedCount) {
+    JsonList<JsonOptionSet> optionSets = content.getList("optionSets", JsonOptionSet.class);
+    assertEquals(expectedCount, optionSets.size());
+    optionSets.forEach(optionSet -> assertEquals(2, optionSet.getOptions().size()));
+  }
+
+  private static JsonOptionSet findOptionSet(JsonObject content, String uid) {
+    return content.getList("optionSets", JsonOptionSet.class).stream()
+        .filter(optionSet -> uid.equals(optionSet.getId()))
+        .findFirst()
+        .orElseThrow();
+  }
+
+  /** Evicts all option related second-level cache regions so a test starts cold. */
+  private void evictOptionRegions() {
+    org.hibernate.Cache cache = entityManagerFactory.unwrap(SessionFactory.class).getCache();
+    cache.evictEntityData(OptionSet.class);
+    cache.evictEntityData(Option.class);
+    cache.evictCollectionData(OPTIONS_COLLECTION_REGION);
+  }
+}
diff --git a/dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/option/OptionSetController.java b/dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/option/OptionSetController.java
index 8de0792f4028..4355fb5d4f49 100644
--- a/dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/option/OptionSetController.java
+++ b/dhis-2/dhis-web-api/src/main/java/org/hisp/dhis/webapi/controller/option/OptionSetController.java
@@ -31,11 +31,13 @@
 
 import static org.hisp.dhis.dxf2.webmessage.WebMessageUtils.notFound;
 
+import java.util.List;
 import lombok.AllArgsConstructor;
 import org.hisp.dhis.common.OpenApi;
 import org.hisp.dhis.dxf2.metadata.MetadataExportParams;
 import org.hisp.dhis.dxf2.webmessage.WebMessageException;
 import org.hisp.dhis.feedback.ConflictException;
+import org.hisp.dhis.fieldfiltering.FieldFilterParser;
 import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.option.OptionSet;
 import org.hisp.dhis.query.GetObjectListParams;
@@ -76,6 +78,29 @@ public ResponseEntity<MetadataExportParams> getOptionSetWithDependencies(
     return ResponseEntity.ok(exportParams);
   }
 
+  /**
+   * Bulk-initializes the options collections of the listed option sets before serialization, but
+   * only when the requested fields actually include {@code options}. Without this every option set
+   * in the page lazily loads its collection with one query during field filtering (DHIS2-21905).
+   * Field inclusion is decided on the expanded field paths, so presets like {@code *} and nested
+   * {@code options[...]} blocks are handled and requests without options never load them.
+   */
+  @Override
+  protected void postProcessResponseEntities(
+      List<OptionSet> entityList, GetObjectListParams params) {
+    if (entityList.isEmpty() || !includesOptions(params)) {
+      return;
+    }
+    optionService.preloadOptions(entityList);
+  }
+
+  private boolean includesOptions(GetObjectListParams params) {
+    return fieldPathHelper
+        .apply(FieldFilterParser.parse(params.getFieldsJsonList()), OptionSet.class)
+        .stream()
+        .anyMatch(path -> "options".contentEquals(path.getPath().head()));
+  }
+
   @Override
   protected void preCreateEntity(OptionSet entity) throws ConflictException {
     optionService.validateOptionSet(entity);