refactor: simplify brand-vs-competitors to single view query with aggregate param

Replace the two-step PostgREST pattern (discover dates from
brand_presence_executions, then chunked .in() queries against the view)
with a single direct query using .gte()/.lte() date-range filters on
brand_vs_competitors_by_date. The regular VIEW supports WHERE pushdown
into partition-pruned scans, making the separate date discovery step
unnecessary.

Add aggregate=true query parameter that rolls up across
categoryName/regionCode server-side, producing one row per
(competitor, executionDate) — the shape the Market Tracking chart
needs directly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rainer-friederich

docs/llmo-brandalf-apis/brand-vs-competitors-api.md

@@ -27,6 +27,7 @@ Returns aggregated competitor mention/citation data for a site. Internally perfo
 | `model` | — | string | No | `chatgpt` | LLM model |
 | `categoryName` | `category_name` | string | No | — | Filter by category name |
 | `regionCode` | `region_code`, `region` | string | No | — | Filter by region code |
+| `aggregate` | — | boolean | No | `false` | Roll up across categoryName/regionCode |
 
 ---
 
@@ -42,26 +43,34 @@ GET /org/44568c3e-efd4-4a7f-8ecd-8caf615f836c/brands/all/brand-presence/brand-vs
 GET /org/44568c3e-efd4-4a7f-8ecd-8caf615f836c/brands/019cb903-1184-7f92-8325-f9d1176af316/brand-presence/brand-vs-competitors?siteId=c2473d89-e997-458d-a86d-b4096649c12b&startDate=2026-01-01&endDate=2026-03-31&categoryName=SEO&regionCode=US
 ```
 
----
+**Aggregated for Market Tracking chart (one row per competitor per week):**
+```
+GET /org/44568c3e-efd4-4a7f-8ecd-8caf615f836c/brands/all/brand-presence/brand-vs-competitors?siteId=c2473d89-e997-458d-a86d-b4096649c12b&aggregate=true
+```
 
-## Internal Queries (PostgREST)
+---
 
-This endpoint performs two sequential PostgREST queries:
+## Internal Query (PostgREST)
 
-**Step 1 — Discover execution dates:**
-- Queries `brand_presence_executions` table
-- Selects `execution_date`, filtered by `organization_id`, `site_id`, `model`, date range (`gte`/`lte`), optionally `brand_id`
-- Deduplicates dates client-side via `Set`
+Single query against the `brand_vs_competitors_by_date` VIEW with date-range filters:
 
-**Step 2 — Query competitor aggregation:**
-- Queries `brand_vs_competitors_by_date` VIEW
 - Selects: `site_id`, `brand_id`, `brand_name`, `model`, `execution_date`, `category_name`, `region_code`, `competitor`, `total_mentions`, `total_citations`
-- Uses `.in('execution_date', dates)` with chunking (50 dates per chunk)
+- Filters: `organization_id`, `site_id`, `model`, `execution_date` (gte/lte date range)
 - Optional filters: `brand_id`, `category_name`, `region_code`
-- Row limit: 5000 per chunk
+- Row limit: 5000
+
+The VIEW is a regular (non-materialized) view — PostgreSQL pushes WHERE clauses through the GROUP BY into partition-pruned, index-covered scans on the source tables.
 
 The underlying VIEW aggregates `executions_competitor_data` joined with `brand_presence_executions` and `organizations`, grouping by competitor (using `COALESCE(parent_company, competitor)` for fallback).
 
+### Aggregation mode
+
+By default, the response returns rows at `(competitor, executionDate, categoryName, regionCode)` granularity.
+
+With `aggregate=true`, the server rolls up across `categoryName`/`regionCode` and returns one row per `(competitor, executionDate)` — the shape the **Market Tracking chart** needs directly. Aggregated rows omit `categoryName` and `regionCode`.
+
+Category/region filters still apply *before* aggregation, so `aggregate=true&categoryName=SEO` returns chart-ready totals scoped to the SEO category.
+
 ---
 
 ## Response Format

docs/openapi/llmo-api.yaml

@@ -1966,9 +1966,10 @@ llmo-brand-vs-competitors:
     summary: Get brand vs competitors aggregated data
     description: |
       Returns aggregated competitor mention/citation data for a site.
-      Internally performs two PostgREST queries: first discovers execution
-      dates from brand_presence_executions, then queries the
-      brand_vs_competitors_by_date view with those dates.
+      Queries the brand_vs_competitors_by_date view directly with date-range
+      filters. Response rows are at (competitor, executionDate, categoryName,
+      regionCode) granularity — aggregate across categoryName/regionCode
+      client-side for chart totals.
     operationId: getBrandVsCompetitors
     parameters:
       - name: siteId
@@ -2011,6 +2012,16 @@ llmo-brand-vs-competitors:
         description: Filter by region code (e.g. US, EU)
         schema:
           type: string
+      - name: aggregate
+        in: query
+        required: false
+        description: >
+          When true, rolls up across categoryName/regionCode to return one row
+          per (competitor, executionDate). Aggregated rows omit categoryName and
+          regionCode. Use for Market Tracking chart totals.
+        schema:
+          type: boolean
+          default: false
     responses:
       '200':
         description: Aggregated competitor data per execution date

src/controllers/llmo/llmo-brand-presence.js

@@ -2537,17 +2537,44 @@ function parseBrandVsCompetitorsParams(context) {
     model: q.model || q.platform,
     categoryName: q.categoryName || q.category_name,
     regionCode: q.regionCode || q.region_code || q.region,
+    aggregate: q.aggregate === 'true' || q.aggregate === true,
   };
 }
 
+/**
+ * Rolls up view rows by (siteId, brandId, brandName, model, executionDate, competitor),
+ * summing totalMentions and totalCitations across categoryName/regionCode.
+ */
+function aggregateCompetitorRows(rows) {
+  const map = new Map();
+  for (const row of rows) {
+    const key = `${row.site_id}|${row.brand_id}|${row.model}|${row.execution_date}|${row.competitor}`;
+    const existing = map.get(key);
+    if (existing) {
+      existing.total_mentions += row.total_mentions || 0;
+      existing.total_citations += row.total_citations || 0;
+    } else {
+      map.set(key, {
+        site_id: row.site_id,
+        brand_id: row.brand_id,
+        brand_name: row.brand_name,
+        model: row.model,
+        execution_date: row.execution_date,
+        competitor: row.competitor,
+        total_mentions: row.total_mentions || 0,
+        total_citations: row.total_citations || 0,
+      });
+    }
+  }
+  return [...map.values()];
+}
+
 /**
  * Creates the getBrandVsCompetitors handler.
- * Single endpoint that internally makes two PostgREST calls:
- * 1. Query brand_presence_executions to discover execution dates for the site
- * 2. Query brand_vs_competitors_by_date VIEW with those dates
- *
- * This keeps date-range logic in the application layer while the DB provides
- * simple view-based aggregation with partition-pruned queries.
+ * Queries the brand_vs_competitors_by_date VIEW directly with date-range filters.
+ * The VIEW is a regular (non-materialized) view — PostgreSQL pushes WHERE clauses
+ * through the GROUP BY into partition-pruned, index-covered scans on the source
+ * tables, so no separate execution-date discovery step is needed.
  * @param {Function} getOrgAndValidateAccess - Async (context) => { organization }
  */
 export function createBrandVsCompetitorsHandler(getOrgAndValidateAccess) {
@@ -2581,77 +2608,55 @@ export function createBrandVsCompetitorsHandler(getOrgAndValidateAccess) {
         return forbidden('Site does not belong to the organization');
       }
 
-      // Step 1: Get execution dates for the site
-      let datesQuery = client
-        .from('brand_presence_executions')
-        .select('execution_date')
+      // Query the view directly — date-range filters push down through the
+      // GROUP BY into partition-pruned scans on the underlying tables.
+      let q = client
+        .from('brand_vs_competitors_by_date')
+        .select('site_id, brand_id, brand_name, model, execution_date, category_name, region_code, competitor, total_mentions, total_citations')
         .eq('organization_id', organizationId)
         .eq('site_id', params.siteId)
         .eq('model', model)
         .gte('execution_date', startDate)
         .lte('execution_date', endDate);
 
       if (filterByBrandId) {
-        datesQuery = datesQuery.eq('brand_id', filterByBrandId);
+        q = q.eq('brand_id', filterByBrandId);
       }
-
-      // Use high row limit — we only extract distinct dates, but the table may have
-      // many rows per date (multiple brands/models/categories). Same rationale as
-      // WEEKS_QUERY_LIMIT in createBrandPresenceWeeksHandler.
-      const { data: datesData, error: datesError } = await datesQuery.limit(WEEKS_QUERY_LIMIT);
-
-      if (datesError) {
-        ctx.log.error(`Brand vs competitors execution dates error: ${datesError.message}`);
-        return badRequest(datesError.message);
+      if (shouldApplyFilter(params.categoryName)) {
+        q = q.eq('category_name', params.categoryName);
       }
-
-      const dateSet = new Set();
-      (datesData || []).forEach((r) => {
-        if (r.execution_date) dateSet.add(String(r.execution_date).slice(0, 10));
-      });
-      const executionDates = [...dateSet].sort((a, b) => b.localeCompare(a));
-
-      if (executionDates.length === 0) {
-        return ok({ competitorData: [] });
+      if (shouldApplyFilter(params.regionCode)) {
+        q = q.eq('region_code', params.regionCode);
       }
 
-      // Step 2: Query the brand_vs_competitors_by_date view with those dates
-      const chunks = [];
-      for (let i = 0; i < executionDates.length; i += IN_FILTER_CHUNK_SIZE) {
-        chunks.push(executionDates.slice(i, i + IN_FILTER_CHUNK_SIZE));
-      }
+      const { data, error } = await q.limit(QUERY_LIMIT);
 
-      const results = await Promise.all(chunks.map((chunk) => {
-        let q = client
-          .from('brand_vs_competitors_by_date')
-          .select('site_id, brand_id, brand_name, model, execution_date, category_name, region_code, competitor, total_mentions, total_citations')
-          .eq('organization_id', organizationId)
-          .eq('model', model)
-          .in('execution_date', chunk)
-          .eq('site_id', params.siteId);
-
-        if (filterByBrandId) {
-          q = q.eq('brand_id', filterByBrandId);
-        }
-        if (shouldApplyFilter(params.categoryName)) {
-          q = q.eq('category_name', params.categoryName);
-        }
-        if (shouldApplyFilter(params.regionCode)) {
-          q = q.eq('region_code', params.regionCode);
-        }
+      if (error) {
+        ctx.log.error(`Brand vs competitors PostgREST error: ${error.message}`);
+        return badRequest(error.message);
+      }
 
-        return q.limit(QUERY_LIMIT);
-      }));
+      const rows = data || [];
 
-      const failed = results.find((r) => r.error);
-      if (failed) {
-        ctx.log.error(`Brand vs competitors PostgREST error: ${failed.error.message}`);
-        return badRequest(failed.error.message);
+      // When aggregate=true, roll up across categoryName/regionCode to produce
+      // one row per (competitor, executionDate) — the shape the Market Tracking
+      // chart needs directly.
+      if (params.aggregate) {
+        const aggregated = aggregateCompetitorRows(rows);
+        const competitorData = aggregated.map((row) => ({
+          siteId: row.site_id,
+          brandId: row.brand_id,
+          brandName: row.brand_name,
+          model: row.model,
+          executionDate: row.execution_date,
+          competitor: row.competitor,
+          totalMentions: row.total_mentions,
+          totalCitations: row.total_citations,
+        }));
+        return ok({ competitorData });
       }
 
-      const allRows = results.flatMap((r) => r.data || []);
-
-      const competitorData = allRows.map((row) => ({
+      const competitorData = rows.map((row) => ({
         siteId: row.site_id,
         brandId: row.brand_id,
         brandName: row.brand_name,