fix(core): Optimize collection variants N+1 and persist catalog filters

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

@@ -0,0 +1,189 @@
+/* eslint-disable no-console */
+import { ID, FacetValue, VendureConfig } from '@vendure/core'; 
+import { createTestEnvironment } from '@vendure/testing';  
+import { gql } from 'graphql-tag';
+import path from 'path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { initialData } from '../e2e-initial-data';
+import { testConfig } from '../test-config';
+
+describe('ListQueryBuilder Optimization Benchmark', () => {
+    let capturedQueries: string[] = [];
+    const baseConfig = testConfig();
+
+    const benchmarkConfig: VendureConfig = {
+        ...baseConfig,
+        customFields: {
+            Product: [
+                {
+                    name: 'testManyToMany',
+                    type: 'relation',
+                    entity: FacetValue,
+                    graphQLType: 'FacetValue',
+                    list: true,
+                },
+                {
+                    name: 'testManyToOne',
+                    type: 'relation',
+                    entity: FacetValue,
+                    graphQLType: 'FacetValue',
+                    list: false,
+                },
+            ],
+        },
+        dbConnectionOptions: {
+            ...baseConfig.dbConnectionOptions,
+            logging: ['query'],
+            logger: {
+                logQuery(query: string) {
+                    if (
+                        query.includes('SELECT') &&
+                        (query.includes('"product"') || query.includes('`product`'))
+                    ) {
+                        capturedQueries.push(query);
+                    }
+                },
+                logQueryError: (error: string) => console.error(error),
+                logQuerySlow: (time: number, query: string) => console.warn(query, time),
+                logSchemaBuild: () => {
+                    /* no-op */
+                },
+                logMigration: () => {
+                    /* no-op */
+                },
+                log: () => {
+                    /* no-op */
+                },
+            } as any,
+        },
+    };
+
+    const { server, adminClient } = createTestEnvironment(benchmarkConfig);
+
+    beforeAll(async () => {
+        await server.init({
+            initialData,
+            productsCsvPath: path.join(__dirname, '../../packages/core/e2e/fixtures/e2e-products-minimal.csv'), 
+            customerCount: 1,
+        });
+        await adminClient.asSuperAdmin();
+    }, 240000);
+
+    afterAll(async () => {
+        await server.destroy();
+    });
+
+    it('uses multiple EXISTS for ManyToMany custom field relation AND filter', async () => {
+        const GET_PRODUCTS = gql`
+            query GetProducts($options: ProductListOptions) {
+                products(options: $options) {
+                    items {
+                        id
+                    }
+                    totalItems
+                }
+            }
+        `;
+
+        capturedQueries = [];
+
+        await adminClient.query(GET_PRODUCTS, {
+            options: {
+                filter: {
+                    _and: [
+                        { testManyToManyId: { eq: '1' } },
+                        { testManyToManyId: { eq: '3' } }
+                    ],
+                },
+            },
+        });
+
+        const lastQuery = capturedQueries.slice().reverse().find(
+            q => q.includes('WHERE') && q.includes('testManyToMany') && !/SELECT\s+COUNT/i.test(q),
+        );
+        expect(lastQuery, 'Should have a query with WHERE and testManyToMany').toBeDefined();
+        if (lastQuery) {
+            const existsCount = (lastQuery.match(/EXISTS/g) || []).length;
+            expect(existsCount).toBe(2);
+            // Verify no JOIN was added for the filter
+            expect(lastQuery).not.toContain('LEFT JOIN');
+        }
+
+        // Verify that the query executes and returns a valid paginated result
+        // Even if empty, totalItems should be a number.
+        const { products } = await adminClient.query(GET_PRODUCTS, {
+            options: { filter: { testManyToManyId: { eq: '1' } } }
+        });
+        expect(products.totalItems).toBeDefined();
+        expect(typeof products.totalItems).toBe('number');
+    });
+
+    it('uses EXISTS for ManyToOne custom field relation when filtering (optimized)', async () => {
+        const GET_PRODUCTS = gql`
+            query GetProducts($options: ProductListOptions) {
+                products(options: $options) {
+                    items {
+                        id
+                    }
+                    totalItems
+                }
+            }
+        `;
+
+        capturedQueries = [];
+
+        await adminClient.query(GET_PRODUCTS, {
+            options: {
+                filter: {
+                    testManyToOneId: { eq: '1' },
+                },
+            },
+        });
+
+        const lastQuery = capturedQueries.slice().reverse().find(
+            q => q.includes('WHERE') && q.includes('testManyToOne') && !/SELECT\s+COUNT/i.test(q),
+        );
+        expect(lastQuery, 'Should have a query with WHERE and testManyToOne').toBeDefined();
+        if (lastQuery) {
+            const existsCount = (lastQuery.match(/EXISTS/g) || []).length;
+            expect(existsCount).toBe(1);
+            // Verify no JOIN was added for the ManyToOne filter (optimization)
+            expect(lastQuery).not.toContain('LEFT JOIN');
+        }
+    });
+
+    it('uses JOIN for ManyToOne custom field relation when sorting', async () => {
+        const GET_PRODUCTS = gql`
+            query GetProducts($options: ProductListOptions) {
+                products(options: $options) {
+                    items {
+                        id
+                    }
+                }
+            }
+        `;
+
+        capturedQueries = [];
+
+        await adminClient.query(GET_PRODUCTS, {
+            options: {
+                sort: {
+                    testManyToOneId: 'ASC',
+                },
+            },
+        });
+
+        const lastQuery = capturedQueries.slice().reverse().find(
+            q => q.includes('testManyToOne') && !/SELECT\s+COUNT/i.test(q),
+        );
+        expect(lastQuery, 'Should have a query with testManyToOne').toBeDefined();
+        if (lastQuery) {
+            // Verify JOIN was added for sorting
+            expect(lastQuery).toContain('LEFT JOIN');
+            // EXISTS is not used for sorting
+            const existsCount = (lastQuery.match(/EXISTS/g) || []).length;
+            expect(existsCount).toBe(0);
+        }
+    });
+});

packages/core/src/api/resolvers/admin/collection.resolver.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/entity/collection-entity.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/common/constants.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;