perf(core): Optimize collection variants N+1 queries with batch loading

Author: RubenDarioGuerreroNeira

e2e-common/benchmarks/benchmark-list-query.e2e-spec.ts

@@ -18,7 +18,7 @@ import { PaginatedList } from '@vendure/common/lib/shared-types';
 import { GraphQLResolveInfo } from 'graphql';
 
 import { RequestContextCacheService } from '../../../cache/request-context-cache.service';
-import { CacheKey } from '../../../common/constants';
+import { CacheKey, COLLECTION_VARIANTS_CACHE_RELATIONS } from '../../../common/constants';
 import { UserInputError } from '../../../common/error/errors';
 import { Translated } from '../../../common/types/locale-types';
 import { CollectionFilter } from '../../../config/catalog/collection-filter';
@@ -66,11 +66,20 @@ export class CollectionResolver {
         const collections = await this.collectionService.findAll(ctx, args.options || undefined, relations);
         // Cache the variant counts query promise if productVariantCount is requested,
         // allowing the DB query to start before the field resolvers are called
+        const collectionIds = collections.items.map(c => c.id);
         if (isFieldInSelection(info, 'productVariantCount')) {
-            const collectionIds = collections.items.map(c => c.id);
             const countsPromise = this.collectionService.getProductVariantCounts(ctx, collectionIds);
             this.requestContextCache.set(ctx, CacheKey.CollectionVariantCounts, countsPromise);
         }
+        if (isFieldInSelection(info, 'productVariants')) {
+            const variantsPromise = this.collectionService.getProductVariantsForCollections(
+                ctx,
+                collectionIds,
+                undefined,
+                [...COLLECTION_VARIANTS_CACHE_RELATIONS],
+            );
+            this.requestContextCache.set(ctx, CacheKey.CollectionVariants, variantsPromise);
+        }
         return collections;
     }
 

packages/core/src/api/resolvers/admin/collection.resolver.ts

@@ -8,10 +8,11 @@ import {
 import { ID, PaginatedList } from '@vendure/common/lib/shared-types';
 
 import { RequestContextCacheService } from '../../../cache/request-context-cache.service';
-import { CacheKey } from '../../../common/constants';
+import { CacheKey, COLLECTION_VARIANTS_CACHE_RELATIONS } from '../../../common/constants';
 import { ListQueryOptions } from '../../../common/types/common-types';
 import { Translated } from '../../../common/types/locale-types';
 import { CollectionFilter } from '../../../config/catalog/collection-filter';
+import { ConfigService } from '../../../config/config.service';
 import { Asset, Collection, Product, ProductVariant } from '../../../entity';
 import { LocaleStringHydrator } from '../../../service/helpers/locale-string-hydrator/locale-string-hydrator';
 import { AssetService } from '../../../service/services/asset.service';
@@ -33,6 +34,7 @@ export class CollectionEntityResolver {
         private localeStringHydrator: LocaleStringHydrator,
         private configurableOperationCodec: ConfigurableOperationCodec,
         private requestContextCache: RequestContextCacheService,
+        private configService: ConfigService,
     ) {}
 
     @ResolveField()
@@ -63,6 +65,40 @@ export class CollectionEntityResolver {
         @Api() apiType: ApiType,
         @Relations({ entity: ProductVariant, omit: ['assets'] }) relations: RelationPaths<ProductVariant>,
     ): Promise<PaginatedList<Translated<ProductVariant>>> {
+        const isDefaultOptions = !args.options || Object.keys(args.options).length === 0;
+        if (isDefaultOptions && apiType === 'admin') {
+            const cachedVariantsPromise = this.requestContextCache.get<
+                Promise<Map<string, ProductVariant[]>>
+            >(ctx, CacheKey.CollectionVariants);
+            if (cachedVariantsPromise) {
+                const variantsMap = await cachedVariantsPromise;
+                const variants = variantsMap.get(String(collection.id));
+                if (variants) {
+                    // Check if the requested relations are compatible with the cached data.
+                    // The cache was populated with default relations defined by COLLECTION_VARIANTS_CACHE_RELATIONS.
+                    // We can use the cache ONLY if the requested relations are a subset of or equal to the default relations.
+                    const isCacheCompatible = relations.every(rel =>
+                        (COLLECTION_VARIANTS_CACHE_RELATIONS as readonly string[]).includes(rel),
+                    );
+
+                    if (isCacheCompatible) {
+                        // Cache is compatible, use it.
+                        const { adminListQueryLimit } = this.configService.apiOptions;
+                        const skip = args.options?.skip ?? 0;
+                        const take = args.options?.take ?? adminListQueryLimit;
+                        const items = await this.productVariantService.applyPricesAndTranslateVariants(
+                            ctx,
+                            variants.slice(skip, skip + take),
+                        );
+                        return {
+                            items,
+                            totalItems: variants.length,
+                        };
+                    }
+                }
+            }
+        }
+
         let options: ListQueryOptions<Product> = args.options;
         if (apiType === 'shop') {
             options = {

packages/core/src/api/resolvers/entity/collection-entity.resolver.ts

@@ -85,6 +85,12 @@ export const CacheKey = {
     ActiveTaxZone: (channelId: ID) => `ActiveTaxZone:${channelId}`,
     ActiveTaxZone_PPA: (channelId: ID) => `ActiveTaxZone_PPA:${channelId}`,
     CollectionVariantCounts: 'CollectionService.getProductVariantCounts',
+    CollectionVariants: 'CollectionService.getProductVariantsForCollections',
     ExhaustedPromotions: (channelId: ID, customerId: ID | undefined) =>
         `ExhaustedPromotions:${channelId}:${customerId ?? 'guest'}`,
 };
+
+/**
+ * The default relations used when pre-caching product variants for collections.
+ */
+export const COLLECTION_VARIANTS_CACHE_RELATIONS = ['taxCategory'] as const;

packages/core/src/common/constants.ts

@@ -437,7 +437,11 @@ export class ListQueryBuilder implements OnApplicationBootstrap {
         const { customPropertyPath } = condition.isExistsCondition;
         const pathParts = customPropertyPath.split('.');
 
-        if (pathParts.length < 2) {
+        // Only handle single-hop paths (e.g., 'facetValues.id'). Multi-hop paths like
+        // 'facetValues.term.id' cannot be expressed as a simple EXISTS subquery
+        // because the column being filtered is on a table reachable only through
+        // the related entity, not on the related entity itself.
+        if (pathParts.length !== 2) {
             return null;
         }
 
@@ -480,7 +484,10 @@ export class ListQueryBuilder implements OnApplicationBootstrap {
         // Helper to escape identifiers for the current database driver (handles PostgreSQL quoting)
         const escapeId = (name: string) => mainQb.connection.driver.escape(name);
         const escapeTablePath = (path: string) =>
-            path.split('.').map(segment => mainQb.connection.driver.escape(segment)).join('.');
+            path
+                .split('.')
+                .map(segment => mainQb.connection.driver.escape(segment))
+                .join('.');
 
         let existsQuery: string;
 

packages/core/src/service/helpers/list-query-builder/list-query-builder.ts

@@ -207,7 +207,7 @@ function getToManyRelationCustomProperties<T extends VendureEntity>(
 
         // Parse the path to get the relation name (e.g., 'facetValues.id' -> 'facetValues')
         const pathParts = path.split('.');
-        if (pathParts.length < 2) {
+        if (pathParts.length !== 2) {
             continue;
         }
 

packages/core/src/service/helpers/list-query-builder/parse-filter-params.ts

@@ -323,7 +323,7 @@ export class CollectionService implements OnModuleInit {
      * This performs a single bulk query to get counts for all provided collection IDs,
      * avoiding N+1 query issues when resolving productVariantCount on multiple collections.
      */
-    async getProductVariantCounts(ctx: RequestContext, collectionIds: ID[]): Promise<Map<ID, number>> {
+    async getProductVariantCounts(ctx: RequestContext, collectionIds: ID[]): Promise<Map<string, number>> {
         if (collectionIds.length === 0) {
             return new Map();
         }
@@ -344,9 +344,7 @@ export class CollectionService implements OnModuleInit {
             .groupBy('collection.id')
             .getRawMany<{ collectionId: string; count: string }>();
 
-        const countMap = new Map<ID, number>();
-        // Normalize IDs to strings to ensure consistent Map key types,
-        // since raw query results return collectionId as string
+        const countMap = new Map<string, number>();
         for (const id of collectionIds) {
             countMap.set(String(id), 0);
         }
@@ -490,7 +488,7 @@ export class CollectionService implements OnModuleInit {
         ctx: RequestContext,
         input: PreviewCollectionVariantsInput,
         options?: ListQueryOptions<ProductVariant>,
-        relations?: RelationPaths<Collection>,
+        relations?: RelationPaths<ProductVariant>,
     ): Promise<PaginatedList<ProductVariant>> {
         const applicableFilters = this.getCollectionFiltersFromInput(input);
         if (input.parentId && input.inheritFilters) {
@@ -503,13 +501,18 @@ export class CollectionService implements OnModuleInit {
             );
             applicableFilters.push(...parentFilters, ...ancestorFilters);
         }
-        let qb = this.listQueryBuilder.build(ProductVariant, options, {
-            relations: relations ?? ['taxCategory'],
-            channelId: ctx.channelId,
-            where: { deletedAt: IsNull() },
-            ctx,
-            entityAlias: 'productVariant',
-        });
+
+        let qb = this.listQueryBuilder.build(
+            ProductVariant,
+            options || { take: undefined, skip: undefined },
+            {
+                relations: relations ?? ['taxCategory'],
+                channelId: ctx.channelId,
+                where: { deletedAt: IsNull() },
+                ctx,
+                entityAlias: 'productVariant',
+            },
+        );
 
         const { collectionFilters } = this.configService.catalogOptions;
         for (const filterType of collectionFilters) {
@@ -713,6 +716,86 @@ export class CollectionService implements OnModuleInit {
         return filters;
     }
 
+    /**
+     * Returns a Map of collection IDs to their associated product variants.
+     * This performs a single bulk query to get all variants for all provided collection IDs,
+     * avoiding N+1 query issues when resolving variants on multiple collections.
+     */
+    async getProductVariantsForCollections(
+        ctx: RequestContext,
+        collectionIds: ID[],
+        options?: ListQueryOptions<ProductVariant>,
+        relations?: RelationPaths<ProductVariant>,
+    ): Promise<Map<string, ProductVariant[]>> {
+        if (collectionIds.length === 0) {
+            return new Map();
+        }
+
+        // Note: This method intentionally returns ALL matching variants without applying
+        // the default admin/shop list query limit. This is safe because it is used only
+        // for batch pre-caching in the admin collection list, where the number of requested
+        // collections is small and controlled by the UI page size.
+        //
+        // Risk: For catalogs with a very large number of product variants per collection,
+        // this query can become expensive. If that becomes a real issue, per-collection
+        // pagination (Option B) should be implemented in a follow-up PR.
+        const qb = this.listQueryBuilder.build(ProductVariant, options ?? {}, {
+            relations: relations ?? ['taxCategory'],
+            channelId: ctx.channelId,
+            where: { deletedAt: IsNull() },
+            ctx,
+            entityAlias: 'productVariant',
+        });
+
+        if (options?.take === undefined) {
+            qb.take(undefined);
+        }
+        if (options?.skip === undefined) {
+            qb.skip(undefined);
+        }
+
+        // We explicitly join with the product to ensure we filter out soft-deleted products,
+        // matching the behavior of other collection-related variant queries.
+        qb.innerJoin('productvariant.collections', 'collection', 'collection.id IN (:...collectionIds)', {
+            collectionIds,
+        })
+            .andWhere('product.deletedAt IS NULL')
+            .addSelect('collection.id', 'collectionId')
+            // Explicitly select `productvariant.id` so we can reliably read the join result key
+            // without depending on TypeORM's auto-generated aliases for raw queries.
+            .addSelect('productvariant.id', 'variantId');
+
+        const { entities: allVariants, raw: rawResults } = await qb.getRawAndEntities();
+
+        const variantsById = new Map<string, ProductVariant>(allVariants.map(v => [String(v.id), v]));
+
+        const variantsByCollectionId = new Map<string, ProductVariant[]>();
+        const seenInCollection = new Map<string, Set<string>>();
+
+        for (const id of collectionIds) {
+            const idStr = String(id);
+            variantsByCollectionId.set(idStr, []);
+            seenInCollection.set(idStr, new Set());
+        }
+
+        for (const raw of rawResults) {
+            const variantId = String(raw.variantId);
+            const collectionId = String(raw.collectionId);
+            const variant = variantsById.get(variantId);
+
+            if (variant) {
+                const collectionVariants = variantsByCollectionId.get(collectionId);
+                const seenSet = seenInCollection.get(collectionId);
+                if (collectionVariants && seenSet && !seenSet.has(variantId)) {
+                    seenSet.add(variantId);
+                    collectionVariants.push(variant);
+                }
+            }
+        }
+
+        return variantsByCollectionId;
+    }
+
     private chunkArray = <T>(array: T[], chunkSize: number): T[][] => {
         const results = [];
         for (let i = 0; i < array.length; i += chunkSize) {

packages/core/src/service/services/collection.service.ts

@@ -766,11 +766,12 @@ export class ProductVariantService {
     }
 
     /**
-     * @description
-     * Given an array of ProductVariants from the database, this method will apply the correct price and tax
-     * and translate each item.
-     */
-    private async applyPricesAndTranslateVariants(
+     /**
+      * @description
+      * Given an array of ProductVariants from the database, this method will apply the correct price and tax
+      * and translate each item.
+      */
+    async applyPricesAndTranslateVariants(
         ctx: RequestContext,
         variants: ProductVariant[],
     ): Promise<Array<Translated<ProductVariant>>> {

packages/core/src/service/services/product-variant.service.ts

@@ -82,7 +82,7 @@ export class TaxRateService {
         }
         if (hasCategoryIdFilter) {
             effectiveRelations.push('category');
-            customPropertyMap.zoneId = 'category.id';
+            customPropertyMap.categoryId = 'category.id';
         }
         return this.listQueryBuilder
             .build(TaxRate, options, {