fix: avoid OptionSet.getOptions() N+1 in analytics metadata resolution [DHIS2-21975]

QueryItemHelper.getItemOptions and its helpers called
gridHeader.getOptionSetObject().getOptions() directly to resolve option
codes for grid metadata. That collection is L2-cached by ID list only;
reassembling entities under a cold entity-level cache falls back to one
SELECT per option (profiled: 6,713 individual optionvalue selects,
1.38s of a 2s /analytics/events/query response).

Thread an injectable options resolver through QueryItemHelper instead,
wired at the three real callers to OptionService.findOptionsByNamePattern,
which fetches the option set in one query and bypasses the broken
collection-cache path entirely. Matching semantics are unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jason-p-pickering

dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/common/processing/MetadataDimensionsHandler.java

@@ -52,6 +52,7 @@
 import org.hisp.dhis.common.MetadataItem;
 import org.hisp.dhis.common.QueryItem;
 import org.hisp.dhis.option.Option;
+import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.period.PeriodType;
 
 /**
@@ -66,6 +67,12 @@
  * the risk of bugs.
  */
 public class MetadataDimensionsHandler {
+  private final OptionService optionService;
+
+  MetadataDimensionsHandler(OptionService optionService) {
+    this.optionService = optionService;
+  }
+
   /**
    * Handles all required logic/rules in order to return a map of metadata item identifiers.
    *
@@ -147,7 +154,11 @@ private void putFilterItemsIntoMap(
    */
   private void putQueryItemsIntoMap(
       Map<String, List<String>> dimensionItems, List<QueryItem> items, Grid grid) {
-    Map<String, List<Option>> optionsPresentInGrid = getItemOptions(grid, items);
+    Map<String, List<Option>> optionsPresentInGrid =
+        getItemOptions(
+            grid,
+            items,
+            optionSet -> optionService.findOptionsByNamePattern(optionSet.getUid(), null, null));
 
     for (QueryItem item : items) {
       String itemUid = getItemUid(item);

dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/common/processing/MetadataItemsHandler.java

@@ -64,6 +64,7 @@
 import org.hisp.dhis.dataelement.DataElement;
 import org.hisp.dhis.legend.Legend;
 import org.hisp.dhis.option.Option;
+import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.option.OptionSet;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
 import org.hisp.dhis.period.PeriodDimension;
@@ -83,6 +84,12 @@
  * the risk of bugs.
  */
 public class MetadataItemsHandler {
+  private final OptionService optionService;
+
+  public MetadataItemsHandler(OptionService optionService) {
+    this.optionService = optionService;
+  }
+
   /**
    * Handles all required logic/rules in order to return a map of metadata item identifiers and its
    * respective {@link MetadataItem}.
@@ -103,7 +110,11 @@ Map<String, MetadataItem> handle(
         delegator.getItemsOptions().stream()
             .filter(o -> isInOriginalRequest(o.getUid(), commonRequestParams))
             .collect(toSet());
-    Map<String, List<Option>> optionsPresentInGrid = getItemOptions(grid, items);
+    Map<String, List<Option>> optionsPresentInGrid =
+        getItemOptions(
+            grid,
+            items,
+            optionSet -> optionService.findOptionsByNamePattern(optionSet.getUid(), null, null));
     Set<Option> optionItems = getOptionItems(grid, itemOptions, items, optionsPresentInGrid);
     List<DimensionalObject> allDimensionalObjects = delegator.getAllDimensionalObjects();
     List<DimensionItemKeywords.Keyword> periodKeywords = delegator.getPeriodKeywords();

dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/common/processing/MetadataParamsHandler.java

@@ -65,6 +65,7 @@
 import org.hisp.dhis.common.Grid;
 import org.hisp.dhis.common.MetadataItem;
 import org.hisp.dhis.common.QueryItem;
+import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
 import org.hisp.dhis.user.User;
 import org.springframework.stereotype.Component;
@@ -83,6 +84,12 @@ public class MetadataParamsHandler {
   private static final String DOT = ".";
   private static final String ORG_UNIT_DIM = "ou";
 
+  private final OptionService optionService;
+
+  public MetadataParamsHandler(OptionService optionService) {
+    this.optionService = optionService;
+  }
+
   /**
    * Appends the metadata to the given {@link Grid} based on the given arguments.
    *
@@ -103,7 +110,8 @@ public void handle(
       List<AnalyticsMetaDataKey> userOrgUnitMetaDataKeys =
           getUserOrgUnitsMetadataKeys(commonParsed);
       Map<String, Object> items =
-          new HashMap<>(new MetadataItemsHandler().handle(grid, commonParsed, commonRequest));
+          new HashMap<>(
+              new MetadataItemsHandler(optionService).handle(grid, commonParsed, commonRequest));
 
       commonParsed
           .getAllDimensionIdentifiers()
@@ -116,7 +124,8 @@ public void handle(
       metadataInfo.put(ITEMS.getKey(), items);
 
       metadataInfo.put(
-          DIMENSIONS.getKey(), new MetadataDimensionsHandler().handle(grid, commonParsed));
+          DIMENSIONS.getKey(),
+          new MetadataDimensionsHandler(optionService).handle(grid, commonParsed));
 
       // Org. Units.
       boolean hierarchyMeta = commonRequest.isHierarchyMeta();

dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/event/data/QueryItemHelper.java

@@ -48,6 +48,7 @@
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.function.Function;
 import java.util.stream.Collectors;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.lang3.StringUtils;
@@ -174,18 +175,23 @@ private static Option getOptionByCode(OptionSet set, String code) {
    *
    * @param grid the {@link Grid}.
    * @param queryItems the list of {@link QueryItem}.
+   * @param optionsResolver resolves the {@link Option}s belonging to an {@link OptionSet}. Callers
+   *     backed by a real persistence context should supply a resolver that fetches the options
+   *     directly (e.g. via a service call), rather than {@link OptionSet#getOptions()}, since that
+   *     lazy collection can degrade into one query per option under a cold second-level cache.
    * @return a map of list of options.
    */
-  public static Map<String, List<Option>> getItemOptions(Grid grid, List<QueryItem> queryItems) {
+  public static Map<String, List<Option>> getItemOptions(
+      Grid grid, List<QueryItem> queryItems, Function<OptionSet, List<Option>> optionsResolver) {
     Map<String, List<Option>> options = new HashMap<>();
 
     for (int i = 0; i < grid.getHeaders().size(); ++i) {
       GridHeader gridHeader = grid.getHeaders().get(i);
 
       if (gridHeader.hasOptionSet() && isNotEmpty(grid.getRows())) {
-        options.put(gridHeader.getName(), getItemOptionsThatMatchesRows(grid, i));
+        options.put(gridHeader.getName(), getItemOptionsThatMatchesRows(grid, i, optionsResolver));
       } else if (gridHeader.hasOptionSet() && isEmpty(grid.getRows())) {
-        options.put(gridHeader.getName(), getItemOptionsForEmptyRows(queryItems));
+        options.put(gridHeader.getName(), getItemOptionsForEmptyRows(queryItems, optionsResolver));
       }
     }
 
@@ -255,18 +261,14 @@ private static boolean filtersContainOption(Option option, List<QueryFilter> que
    * @param queryItems the {@link EventQueryParams}.
    * @return the options for empty rows.
    */
-  private static List<Option> getItemOptionsForEmptyRows(List<QueryItem> queryItems) {
+  private static List<Option> getItemOptionsForEmptyRows(
+      List<QueryItem> queryItems, Function<OptionSet, List<Option>> optionsResolver) {
     List<Option> options = new ArrayList<>();
 
     if (isNotEmpty(queryItems)) {
-      List<QueryItem> items = queryItems;
-
-      for (QueryItem item : items) {
-        boolean hasOptions =
-            item.getOptionSet() != null && isNotEmpty(item.getOptionSet().getOptions());
-
-        if (hasOptions && isNotEmpty(item.getFilters())) {
-          options.addAll(getItemOptionsForFilter(item));
+      for (QueryItem item : queryItems) {
+        if (item.getOptionSet() != null && isNotEmpty(item.getFilters())) {
+          options.addAll(getItemOptionsForFilter(item, optionsResolver));
         }
       }
     }
@@ -281,9 +283,12 @@ private static List<Option> getItemOptionsForEmptyRows(List<QueryItem> queryItem
    *
    * @param grid the {@link Grid}.
    * @param columnIndex the column index.
+   * @param optionsResolver resolves the {@link Option}s belonging to an {@link OptionSet} without
+   *     going through {@link OptionSet#getOptions()}.
    * @return a list of matching options.
    */
-  private static List<Option> getItemOptionsThatMatchesRows(Grid grid, int columnIndex) {
+  private static List<Option> getItemOptionsThatMatchesRows(
+      Grid grid, int columnIndex, Function<OptionSet, List<Option>> optionsResolver) {
     if (grid == null || grid.getHeaders() == null || columnIndex < 0) {
       return Collections.emptyList();
     }
@@ -292,15 +297,11 @@ private static List<Option> getItemOptionsThatMatchesRows(Grid grid, int columnI
     }
 
     GridHeader gridHeader = grid.getHeaders().get(columnIndex);
-    if (gridHeader == null
-        || gridHeader.getOptionSetObject() == null
-        || gridHeader.getOptionSetObject().getOptions() == null) {
+    if (gridHeader == null || gridHeader.getOptionSetObject() == null) {
       return Collections.emptyList();
     }
 
-    List<Option> allOptions = gridHeader.getOptionSetObject().getOptions();
-    // Check if there are no options to filter or no rows to check against
-    if (allOptions.isEmpty() || grid.getRows() == null || grid.getRows().isEmpty()) {
+    if (grid.getRows() == null || grid.getRows().isEmpty()) {
       return Collections.emptyList();
     }
 
@@ -315,11 +316,16 @@ private static List<Option> getItemOptionsThatMatchesRows(Grid grid, int columnI
             .collect(Collectors.toSet());
 
     // If there are no distinct, non-null values in the rows for this column, no option can possibly
-    // match.
+    // match, so there is no need to resolve any options at all.
     if (distinctRowCellValues.isEmpty()) {
       return Collections.emptyList();
     }
 
+    List<Option> allOptions = optionsResolver.apply(gridHeader.getOptionSetObject());
+    if (allOptions == null || allOptions.isEmpty()) {
+      return Collections.emptyList();
+    }
+
     // Filter the options
     // For each option, check if its code matches any of the pre-collected distinct row cell values.
     return allOptions.stream()
@@ -400,10 +406,16 @@ public static boolean isItemOptionEqualToRowContent(String code, Object rowConte
    * @param item the {@link QueryItem}.
    * @return a list of options found in the filter.
    */
-  private static List<Option> getItemOptionsForFilter(QueryItem item) {
+  private static List<Option> getItemOptionsForFilter(
+      QueryItem item, Function<OptionSet, List<Option>> optionsResolver) {
     List<Option> options = new ArrayList<>();
+    List<Option> resolvedOptions = optionsResolver.apply(item.getOptionSet());
+
+    if (resolvedOptions == null) {
+      return options;
+    }
 
-    for (Option option : item.getOptionSet().getOptions()) {
+    for (Option option : resolvedOptions) {
       for (QueryFilter filter : item.getFilters()) {
         List<String> filterSplit =
             Arrays.stream(trimToEmpty(filter.getFilter()).split(";")).collect(toList());

dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/tracker/MetadataItemsHandler.java

@@ -91,6 +91,8 @@
 import org.hisp.dhis.i18n.I18nFormat;
 import org.hisp.dhis.i18n.I18nManager;
 import org.hisp.dhis.option.Option;
+import org.hisp.dhis.option.OptionService;
+import org.hisp.dhis.option.OptionSet;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
 import org.hisp.dhis.period.PeriodDimension;
 import org.hisp.dhis.period.PeriodType;
@@ -112,6 +114,8 @@ public class MetadataItemsHandler {
 
   private final I18nManager i18nManager;
 
+  private final OptionService optionService;
+
   /**
    * Adds meta-data values to the given grid based on the given data query parameters.
    *
@@ -187,7 +191,8 @@ private void addUserOrgUnitItems(Map<String, Object> items, EventQueryParams par
    */
   private Set<Option> collectOptionItems(Grid grid, EventQueryParams params) {
     Set<Option> optionItems = new LinkedHashSet<>();
-    Map<String, List<Option>> optionsPresentInGrid = getItemOptions(grid, params.getItems());
+    Map<String, List<Option>> optionsPresentInGrid =
+        getItemOptions(grid, params.getItems(), this::resolveOptions);
 
     if (isNotEmpty(grid.getRows())) {
       optionItems.addAll(
@@ -208,12 +213,25 @@ private Set<Option> collectOptionItems(Grid grid, EventQueryParams params) {
    */
   private Map<String, List<String>> buildDimensionItems(Grid grid, EventQueryParams params) {
     if (params.isComingFromQuery()) {
-      Map<String, List<Option>> optionsPresentInGrid = getItemOptions(grid, params.getItems());
+      Map<String, List<Option>> optionsPresentInGrid =
+          getItemOptions(grid, params.getItems(), this::resolveOptions);
       return getDimensionItems(params, Optional.of(optionsPresentInGrid));
     }
     return getDimensionItems(params, empty());
   }
 
+  /**
+   * Resolves the {@link Option}s belonging to the given {@link OptionSet} directly, instead of
+   * through {@link OptionSet#getOptions()} - that lazy collection can fall back to one query per
+   * option under a cold second-level cache.
+   *
+   * @param optionSet the {@link OptionSet}.
+   * @return the list of {@link Option}.
+   */
+  private List<Option> resolveOptions(OptionSet optionSet) {
+    return optionService.findOptionsByNamePattern(optionSet.getUid(), null, null);
+  }
+
   /**
    * Returns a unified map of metadata item identifiers and {@link MetadataItem}. This method
    * handles both query and non-query scenarios.
@@ -337,7 +355,7 @@ private void addOptionMetadataForQuery(
                     includeDetails ? option.getUid() : null,
                     option.getCode())));
 
-    new org.hisp.dhis.analytics.common.processing.MetadataItemsHandler()
+    new org.hisp.dhis.analytics.common.processing.MetadataItemsHandler(optionService)
         .addOptionsSetIntoMap(metadataItemMap, itemOptions);
   }
 

dhis-2/dhis-services/dhis-service-analytics/src/test/java/org/hisp/dhis/analytics/common/GridAdaptorTest.java

@@ -72,6 +72,7 @@
 import org.hisp.dhis.common.Grid;
 import org.hisp.dhis.i18n.I18n;
 import org.hisp.dhis.i18n.I18nManager;
+import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.program.Program;
 import org.hisp.dhis.program.ProgramStage;
 import org.hisp.dhis.test.TestBase;
@@ -96,6 +97,8 @@ class GridAdaptorTest extends TestBase {
 
   @Mock private I18n i18n;
 
+  @Mock private OptionService optionService;
+
   private GridAdaptor gridAdaptor;
 
   private HeaderParamsHandler headerParamsHandler;
@@ -107,7 +110,7 @@ class GridAdaptorTest extends TestBase {
   @BeforeEach
   void setUp() {
     headerParamsHandler = new HeaderParamsHandler();
-    metadataDetailsHandler = new MetadataParamsHandler();
+    metadataDetailsHandler = new MetadataParamsHandler(optionService);
     schemeIdResponseMapper = new SchemeIdResponseMapper(i18nManager);
     gridAdaptor =
         new GridAdaptor(headerParamsHandler, metadataDetailsHandler, schemeIdResponseMapper);

dhis-2/dhis-services/dhis-service-analytics/src/test/java/org/hisp/dhis/analytics/common/processing/MetadataParamsHandlerTest.java

@@ -51,6 +51,7 @@
 import org.hisp.dhis.common.QueryItem;
 import org.hisp.dhis.common.ValueType;
 import org.hisp.dhis.dataelement.DataElement;
+import org.hisp.dhis.option.OptionService;
 import org.hisp.dhis.program.Program;
 import org.hisp.dhis.program.ProgramStage;
 import org.hisp.dhis.system.grid.ListGrid;
@@ -59,16 +60,19 @@
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 
 @ExtendWith(MockitoExtension.class)
 class MetadataParamsHandlerTest {
 
+  @Mock private OptionService optionService;
+
   private MetadataParamsHandler metadataParamsHandler;
 
   @BeforeEach
   void setUp() {
-    metadataParamsHandler = new MetadataParamsHandler();
+    metadataParamsHandler = new MetadataParamsHandler(optionService);
   }
 
   @Nested