Improve performance of listTemplates API by Pearl1594 · Pull Request #13566 · apache/cloudstack

Pearl1594 · 2026-07-07T18:44:55Z

Description

This PR Adds a fast-path for listTemplates Phase 1 that bypasses template_view,
behind a runtime config flag (default off).

Why

The captured incident query against template_view runs 7,000+ seconds and
drains the DB pool. View materializes ~71k rows for ~4.7k templates due to
LEFT-JOIN row multiplication, OR-join on data_center, and predicates on a
computed column. Phase 1 only needs 6 of the 13 tables.

What changed

BypassTemplateView ConfigKey (template.list.bypass.view, default false,
Global, runtime-toggleable).
TemplateListFilter POJO + canBypass() predicate.
TemplateJoinDao.findDistinctTempZonePairs(filter) — hand-tuned SQL over
vm_template + account + template_store_ref + image_store + template_zone_ref
- data_center; OR-join replaced with COALESCE.
QueryManagerImpl builds the filter and dispatches to bypass when flag is
on AND canBypass() is true. Otherwise falls through to existing path.

Coverage

Bypass handles: id, name, keyword, hypervisor, format, type,
public, featured, bootable, parenttemplateid, accountType,
accountIdIN, zoneid, templateState, removed, onlyReady, pagination,
templatefilter ∈ {self/selfexecutable non-domain-admin, executable,
all admin}.

Falls back to view path: tags, templatefilter ∈ {featured, community,
sharedexecutable, shared, all non-admin, self/selfexecutable for
DOMAIN_ADMIN/RESOURCE_DOMAIN_ADMIN}.

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
Build/CI
Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

* added bypass logic to create template_pair from 6 tables, fallback for hard filters * Removed batching, checking against per pair * follow try-with-resources design * unit tests for the bypass logic * Fix cross-zone template lookup in listTemplates Phase 2 When temp_zone_pair has dcId=0 (cross-zone template with no data_center), use IS NULL predicate instead of broken EQ/IN with literal 0 which never matches NULL rows. * Add filter for non-root domain-admin users --------- Co-authored-by: anishadas <adas33@apple.com> Co-authored-by: Aaron Chung <aaron_chung@apple.com>

Co-authored-by: anishadas <adas33@apple.com> (cherry picked from commit f6c9fd1081f0e1d9386db08e86485b482bf064ab)

codecov · 2026-07-07T18:50:59Z

Codecov Report

❌ Patch coverage is 6.18280% with 349 lines in your changes missing coverage. Please review.
✅ Project coverage is 17.72%. Comparing base (a951ac6) to head (42fe302).
⚠️ Report is 25 commits behind head on 4.22.

Files with missing lines	Patch %	Lines
...a/com/cloud/api/query/dao/TemplateJoinDaoImpl.java	10.37%	189 Missing and 1 partial ⚠️
...va/com/cloud/api/query/dao/TemplateListFilter.java	0.00%	88 Missing and 1 partial ⚠️
...ain/java/com/cloud/api/query/QueryManagerImpl.java	0.00%	70 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               4.22   #13566      +/-   ##
============================================
+ Coverage     17.67%   17.72%   +0.05%     
- Complexity    15797    15910     +113     
============================================
  Files          5923     5927       +4     
  Lines        533349   537533    +4184     
  Branches      65248    66563    +1315     
============================================
+ Hits          94253    95292    +1039     
- Misses       428437   431527    +3090     
- Partials      10659    10714      +55

Flag	Coverage Δ
uitests	`3.65% <ø> (-0.04%)`	⬇️
unittests	`18.81% <6.18%> (+0.06%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ove-listtemplates-perf

vladimirpetrov · 2026-07-13T15:10:51Z

@blueorangutan package

blueorangutan · 2026-07-13T15:12:05Z

@vladimirpetrov a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2026-07-13T16:16:28Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18552

DaanHoogland · 2026-07-20T09:25:26Z

thanks @Pearl1594 , do you have any performance figures? (before vs. after?)

…unt is correct, but lists all templates

sonarqubecloud · 2026-07-21T15:06:36Z

Quality Gate failed

Failed conditions
2.5% Coverage on New Code (required ≥ 40%)

See analysis details on SonarQube Cloud

Damans227 · 2026-07-21T18:44:13Z

 import com.cloud.storage.dao.StoragePoolAndAccessGroupMapDao;
 import com.cloud.cluster.ManagementServerHostPeerJoinVO;

+import com.cloud.template.VirtualMachineTemplate;


Nit: these new imports break alphabetical order here, and the same classes (AccountVO, SSHKeyPairVO, SSHKeyPairDao, InstanceGroupVMMapVO, NicVO, InstanceGroupVMMapDao, NicDao) get removed from their previously-correct alphabetized spots further down in this same diff.

Damans227 · 2026-07-21T18:44:13Z


+    ConfigKey<Boolean> BypassTemplateView = new ConfigKey<>("Advanced", Boolean.class, "template.list.bypass.view",
+            "false",
+            "If true, uses an optimized query path for listing templates and ISOs, which can improve performance on " +


Nit: the concatenated description string has inconsistent leading/trailing space placement across the lines, worth double-checking the rendered text doesn't end up with a missing or doubled space.

Damans227 · 2026-07-21T18:44:13Z

        return new Pair<List<TemplateJoinVO>, Integer>(objects, count);
    }

+    // ============================================================================


Nit: this banner-style comment block doesn't match the rest of the codebase's usual /** javadoc */ or short // comment style.

Damans227 · 2026-07-21T18:44:13Z

+     */
+    private String buildFromClause(TemplateListFilter filter) {
+        StringBuilder from = new StringBuilder()
+                .append("cloud.vm_template vt")


Nit: hardcoding the cloud. schema prefix here is unusual for this codebase's DAOs, worth checking this holds for all deployments.

Damans227 · 2026-07-21T18:44:13Z

+        try {
+            TEMPLATE_JOIN_ID_FIELD = findFieldUpHierarchy(TemplateJoinVO.class, "id");
+            TEMPLATE_JOIN_PAIR_FIELD = findFieldUpHierarchy(TemplateJoinVO.class, "tempZonePair");
+            TEMPLATE_JOIN_ID_FIELD.setAccessible(true);


Nit: reflection to populate TemplateJoinVO's private fields feels like a fairly invasive way to build this VO, a package-visible setter would be less fragile against future field renames.

aniishadas and others added 3 commits July 7, 2026 14:38

Add @ignore, remove logs/comments (#824)

cf6beb4

Co-authored-by: anishadas <adas33@apple.com> (cherry picked from commit f6c9fd1081f0e1d9386db08e86485b482bf064ab)

Improve BypassTemplateView config description and rename helper method

54d4392

Pearl1594 requested a review from nvazquez July 7, 2026 18:44

boring-cyborg Bot added the component:api label Jul 7, 2026

Pearl Dsilva added 2 commits July 7, 2026 15:05

Merge branch '4.22' of https://github.com/apache/cloudstack into impr…

222cf25

…ove-listtemplates-perf

remove logger

21955d9

weizhouapache added this to the 4.22.2 milestone Jul 12, 2026

Fix issue with listing templates when filtered on name / keyword - co…

42fe302

…unt is correct, but lists all templates

Damans227 reviewed Jul 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Improve performance of listTemplates API#13566

Improve performance of listTemplates API#13566
Pearl1594 wants to merge 6 commits into
4.22from
improve-listtemplates-perf

Pearl1594 commented Jul 7, 2026

Uh oh!

codecov Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

vladimirpetrov commented Jul 13, 2026

Uh oh!

blueorangutan commented Jul 13, 2026

Uh oh!

blueorangutan commented Jul 13, 2026

Uh oh!

DaanHoogland commented Jul 20, 2026

Uh oh!

sonarqubecloud Bot commented Jul 21, 2026

Uh oh!

Damans227 Jul 21, 2026

Uh oh!

Damans227 Jul 21, 2026

Uh oh!

Damans227 Jul 21, 2026

Uh oh!

Damans227 Jul 21, 2026

Uh oh!

Damans227 Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Uh oh!

Conversation

Pearl1594 commented Jul 7, 2026

Description

Why

What changed

Coverage

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

Uh oh!

codecov Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vladimirpetrov commented Jul 13, 2026

Uh oh!

blueorangutan commented Jul 13, 2026

Uh oh!

blueorangutan commented Jul 13, 2026

Uh oh!

DaanHoogland commented Jul 20, 2026

Uh oh!

sonarqubecloud Bot commented Jul 21, 2026

Quality Gate failed

Uh oh!

Damans227 Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Damans227 Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Damans227 Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Damans227 Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Damans227 Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

codecov Bot commented Jul 7, 2026 •

edited

Loading