Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(mentions): add the per-answer terms and the Perception read (#1123)

Cihan4fcd6dda04a2
diff --git a/server/src/lib/mentions-rollups.js b/server/src/lib/mentions-rollups.js
index 36b5fc728..4e2343d98 100644
--- a/server/src/lib/mentions-rollups.js
+++ b/server/src/lib/mentions-rollups.js
@@ -3,10 +3,11 @@
*
* The Mentions & Sentiment page reads per-day mention rows instead of
* re-reading a window of answers per load; this module is the only thing
- * that writes them, through the `refresh_mentions_daily` SQL function. It
- * rides on the Insights rollup callers (insights-rollups.js), as the Citations
- * rollups do: a run's days are refreshed when the run stamps, and the daily
- * sweep re-refreshes the trailing days.
+ * that writes them, through the `refresh_mentions_daily` and
+ * `refresh_mention_terms` SQL functions. It rides on the Insights rollup
+ * callers (insights-rollups.js), as the Citations rollups do: a run's days
+ * are refreshed when the run stamps, and the daily sweep re-refreshes the
+ * trailing days.
*
* Best-effort like the other rollups: the rows are derived state, always
* recomputable from prompt_results, so a failure costs freshness until the
@@ -18,22 +19,49 @@ import { logger } from './logger.js';
import { dayChunks, resultDayBound } from './citations-rollups.js';
/**
- * Recompute one brand's mention rollups for an inclusive UTC day range.
- * Resolves to true on success, false otherwise; never throws.
+ * Recompute one brand's mention rollups (00157) and its answers' terms
+ * (00161) for an inclusive UTC day range. Separate calls, because a
+ * sentiment correction (00160) refreshes only the rollups: the rollups in
+ * one, then the terms a day per call, since they read each answer's text
+ * and a few busy days of the largest brand would near the service role's
+ * statement timeout (MENTION_HISTORY_CHUNK_DAYS). Resolves to true when
+ * every call succeeds, false at the first that fails; never throws.
*/
export async function refreshMentionsDaily(brandId, dayFrom, dayTo) {
- const { error } = await supabaseAdmin.rpc('refresh_mentions_daily', {
- p_brand_id: brandId,
- p_day_from: dayFrom,
- p_day_to: dayTo,
- });
- if (error) {
- logger.error({ err: error, brandId, dayFrom, dayTo }, '[mentions-rollups] refresh failed');
- return false;
+ const calls = [
+ ['refresh_mentions_daily', dayFrom, dayTo],
+ ...dayChunks(dayFrom, dayTo, MENTION_HISTORY_CHUNK_DAYS).map(([from, to]) => [
+ 'refresh_mention_terms',
+ from,
+ to,
+ ]),
+ ];
+ for (const [fn, from, to] of calls) {
+ const { error } = await supabaseAdmin.rpc(fn, {
+ p_brand_id: brandId,
+ p_day_from: from,
+ p_day_to: to,
+ });
+ if (error) {
+ logger.error(
+ { err: error, brandId, dayFrom: from, dayTo: to, fn },
+ '[mentions-rollups] refresh failed',
+ );
+ return false;
+ }
}
return true;
}
+/**
+ * Days per history refresh call. Shorter than the citation rollups' two
+ * weeks: the terms (00161) read each answer's text, a few milliseconds per
+ * answer and entity named. The largest brand's busiest days take tens of
+ * seconds each, so even three of them would near the service role's
+ * statement timeout.
+ */
+export const MENTION_HISTORY_CHUNK_DAYS = 1;
+
/**
* Recompute a brand's whole mention history, a chunk at a time so no call
* nears the service role's statement timeout. Resolves to the number of
@@ -44,7 +72,7 @@ export async function refreshMentionHistory(brandId, { pauseMs = 0 } = {}) {
if (!firstDay) return 0;
const lastDay = await resultDayBound(brandId, false);
- const chunks = dayChunks(firstDay, lastDay);
+ const chunks = dayChunks(firstDay, lastDay, MENTION_HISTORY_CHUNK_DAYS);
for (const [from, to] of chunks) {
const ok = await refreshMentionsDaily(brandId, from, to);
if (!ok) throw new Error(`mention rollup refresh failed for ${brandId} ${from}..${to}`);
diff --git a/server/src/lib/mentions-rollups.test.js b/server/src/lib/mentions-rollups.test.js
index c9cb35a70..dacb485a1 100644
--- a/server/src/lib/mentions-rollups.test.js
+++ b/server/src/lib/mentions-rollups.test.js
@@ -33,14 +33,16 @@ beforeEach(() => {
});
describe('refreshMentionsDaily', () => {
- it('calls the refresh function with the brand and inclusive day range', async () => {
+ it('refreshes the rollups for the range, then the terms a day at a time', async () => {
rpc.mockResolvedValue({ error: null });
await expect(refreshMentionsDaily('brand-1', '2026-10-15', '2026-10-17')).resolves.toBe(true);
- expect(rpc).toHaveBeenCalledWith('refresh_mentions_daily', {
- p_brand_id: 'brand-1',
- p_day_from: '2026-10-15',
- p_day_to: '2026-10-17',
- });
+ const args = (from, to) => ({ p_brand_id: 'brand-1', p_day_from: from, p_day_to: to });
+ expect(rpc.mock.calls).toEqual([
+ ['refresh_mentions_daily', args('2026-10-15', '2026-10-17')],
+ ['refresh_mention_terms', args('2026-10-15', '2026-10-15')],
+ ['refresh_mention_terms', args('2026-10-16', '2026-10-16')],
+ ['refresh_mention_terms', args('2026-10-17', '2026-10-17')],
+ ]);
});
// Derived state: a failed refresh costs freshness until the next sweep and
@@ -49,19 +51,26 @@ describe('refreshMentionsDaily', () => {
rpc.mockResolvedValue({ error: { message: 'boom' } });
await expect(refreshMentionsDaily('brand-1', '2026-10-17', '2026-10-17')).resolves.toBe(false);
});
+
+ it('reports a failed terms refresh too', async () => {
+ rpc.mockResolvedValueOnce({ error: null }).mockResolvedValueOnce({ error: { message: 'x' } });
+ await expect(refreshMentionsDaily('brand-1', '2026-10-17', '2026-10-17')).resolves.toBe(false);
+ });
});
describe('refreshMentionHistory', () => {
- it('recomputes the whole history in two-week chunks', async () => {
- resultBounds('2026-09-01', '2026-10-17');
+ it('recomputes the whole history a day at a time', async () => {
+ resultBounds('2026-10-01', '2026-10-03');
rpc.mockResolvedValue({ error: null });
- await expect(refreshMentionHistory('brand-1')).resolves.toBe(4);
- expect(rpc.mock.calls.map(([, args]) => [args.p_day_from, args.p_day_to])).toEqual([
- ['2026-09-01', '2026-09-14'],
- ['2026-09-15', '2026-09-28'],
- ['2026-09-29', '2026-10-12'],
- ['2026-10-13', '2026-10-17'],
+ await expect(refreshMentionHistory('brand-1')).resolves.toBe(3);
+ expect(rpc.mock.calls.map(([fn, args]) => [fn, args.p_day_from, args.p_day_to])).toEqual([
+ ['refresh_mentions_daily', '2026-10-01', '2026-10-01'],
+ ['refresh_mention_terms', '2026-10-01', '2026-10-01'],
+ ['refresh_mentions_daily', '2026-10-02', '2026-10-02'],
+ ['refresh_mention_terms', '2026-10-02', '2026-10-02'],
+ ['refresh_mentions_daily', '2026-10-03', '2026-10-03'],
+ ['refresh_mention_terms', '2026-10-03', '2026-10-03'],
]);
});
@@ -73,9 +82,12 @@ describe('refreshMentionHistory', () => {
it('stops at a failed chunk so the backfill can be run again', async () => {
resultBounds('2026-09-01', '2026-10-17');
- rpc.mockResolvedValueOnce({ error: null }).mockResolvedValueOnce({ error: { message: 'x' } });
+ rpc
+ .mockResolvedValueOnce({ error: null })
+ .mockResolvedValueOnce({ error: null })
+ .mockResolvedValueOnce({ error: { message: 'x' } });
await expect(refreshMentionHistory('brand-1')).rejects.toThrow(
- 'mention rollup refresh failed for brand-1 2026-09-15..2026-09-28',
+ 'mention rollup refresh failed for brand-1 2026-09-02..2026-09-02',
);
});
});
diff --git a/server/src/scripts/backfill-mentions-daily.js b/server/src/scripts/backfill-mentions-daily.js
index 81d3fbcb4..c17954d65 100644
--- a/server/src/scripts/backfill-mentions-daily.js
+++ b/server/src/scripts/backfill-mentions-daily.js
@@ -1,5 +1,6 @@
/**
- * Backfill the Mentions daily rollups (00157) from historical prompt_results.
+ * Backfill the Mentions daily rollups (00157) and per-answer terms (00161)
+ * from historical prompt_results.
*
* Run: `node src/scripts/backfill-mentions-daily.js`
*
@@ -14,7 +15,7 @@
*
* Idempotent and restartable. `refresh_mentions_daily` is delete + insert per
* day range, so an interrupted run can be started again. Chunked by
- * HISTORY_CHUNK_DAYS, with a pause between calls because this shares the
+ * MENTION_HISTORY_CHUNK_DAYS, with a pause between calls because this shares the
* instance with live dashboards.
*/
diff --git a/supabase/migrations/00161_mentions_perception.sql b/supabase/migrations/00161_mentions_perception.sql
new file mode 100644
index 000000000..f4649473d
--- /dev/null
+++ b/supabase/migrations/00161_mentions_perception.sql
@@ -0,0 +1,483 @@
+-- ============================================================================
+-- 00161: What AI associates with each brand (Mentions & Sentiment, MS-09)
+-- ============================================================================
+-- The Perception tab asks what AI says next to a brand: the terms around its
+-- mentions, how they compare with the competitors', and which competitors AI
+-- names beside it. Spec §9 wants it deterministic in V1 (no LLM): the terms
+-- come from the stored answers' text by rule.
+--
+-- * mention_terms(text, names, exclude) takes the sentences that name an
+-- entity (a whole word, ignoring case) and returns their words and
+-- two-word phrases, minus stop words in the languages tracked (Postgres'
+-- Snowball dictionaries), a short list of words answers use about every
+-- brand alike, and the words in `exclude`: every brand's and competitor's
+-- names, and the question's own words (they would rank first for every
+-- brand and say nothing about it). A phrase never spans a comma or a
+-- bracket.
+-- * mentions_answer_terms keeps, per answer and per entity it names (the
+-- brand, or a competitor by id), the distinct terms. One row per answer
+-- and entity, not per term per day: the page's filters (topic, search,
+-- platform, country) and the window before stay available, and the table
+-- grows with the answers, not with the vocabulary.
+-- * refresh_mention_terms fills it for a UTC day range. The server calls it
+-- beside refresh_mentions_daily (00157), for the same days and callers: a
+-- completed run, the nightly sweep and backfill-mentions-daily.js. A
+-- sentiment correction (00160) refreshes only the rollups.
+-- * mentions_perception(...) reads a window and the one before it: the
+-- brand's top terms with their trend, the attributes that tell the brand
+-- and its four most mentioned competitors apart, with each one's share
+-- of mentions, and the competitors named in the same answers as the
+-- brand, now and before.
+--
+-- Terms describe what is said next to a brand, not who it is said about: a
+-- sentence naming two brands lends its words to both. Spec §3 leaves themes
+-- and polarity to the V1.5 classifier.
+
+-- ─── Terms ──────────────────────────────────────────────────────────────────
+
+create or replace function public.mention_stopword(p_word text)
+returns boolean
+language sql
+stable
+parallel safe
+set search_path to 'public', 'pg_catalog'
+as $$
+ select p_word = any (array[
+ 'best', 'top', 'also', 'like', 'well', 'great', 'good', 'better', 'many', 'much',
+ 'more', 'most', 'other', 'others', 'one', 'two', 'three', 'first', 'second',
+ 'third', 'new', 'known', 'popular', 'option', 'options', 'choice', 'choices',
+ 'alternative', 'alternatives', 'include', 'includes', 'including', 'offer',
+ 'offers', 'offering', 'provide', 'provides', 'providing', 'list', 'lists',
+ 'brand', 'brands', 'company', 'companies', 'service', 'services', 'product',
+ 'products', 'platform', 'platforms', 'tool', 'tools', 'solution', 'solutions',
+ 'feature', 'features', 'use', 'used', 'using', 'user', 'users', 'customer',
+ 'customers', 'help', 'helps', 'make', 'makes', 'get', 'gets', 'often',
+ 'especially', 'consider', 'considered', 'overall', 'recommend', 'recommended',
+ 'highly', 'rated', 'review', 'reviews', 'www', 'com', 'http', 'https', 'etc',
+ 'whether', 'however', 'although', 'though', 'still', 'even', 'just', 'really',
+ 'various', 'several', 'number', 'way', 'ways', 'thing', 'things', 'look',
+ 'looking', 'want', 'need', 'needs', 'depending', 'depends', 'based', 'pick',
+ 'picks', 'stand', 'stands', 'out', 'here', 'there', 'below', 'above',
+ -- Where a brand sits in a list, not what it is.
+ 'ahead', 'behind', 'leads', 'lead', 'leading', 'comes', 'come', 'close',
+ 'closely', 'rank', 'ranks', 'ranked', 'spot', 'place', 'placed', 'followed',
+ 'follows', 'next', 'usual',
+ -- How answers talk about anything.
+ 'solid', 'say', 'says', 'said', 'buyer', 'buyers', 'people', 'focus', 'focuses',
+ 'focused', 'mention', 'mentions', 'mentioned', 'reviewer', 'reviewers', 'start',
+ 'starts', 'starting', 'wants', 'worth', 'available'])
+ or ts_lexize('english_stem', p_word) = '{}'
+ or ts_lexize('german_stem', p_word) = '{}'
+ or ts_lexize('french_stem', p_word) = '{}'
+ or ts_lexize('spanish_stem', p_word) = '{}'
+ or ts_lexize('italian_stem', p_word) = '{}'
+ or ts_lexize('portuguese_stem', p_word) = '{}'
+ or ts_lexize('dutch_stem', p_word) = '{}'
+ or ts_lexize('turkish_stem', p_word) = '{}'
+ or ts_lexize('swedish_stem', p_word) = '{}'
+ or ts_lexize('danish_stem', p_word) = '{}'
+ or ts_lexize('norwegian_stem', p_word) = '{}'
+ or ts_lexize('finnish_stem', p_word) = '{}'
+ or ts_lexize('russian_stem', p_word) = '{}';
+$$;
+
+create or replace function public.mention_terms(p_text text, p_names text[], p_exclude text[])
+returns text[]
+language sql
+stable
+parallel safe
+set search_path to 'public', 'pg_catalog'
+as $$
+ with clean as (
+ -- ChatGPT's entity tags read as their names, links as their labels, bare
+ -- URLs and markdown marks dropped.
+ select regexp_replace(regexp_replace(regexp_replace(regexp_replace(coalesce(p_text, ''),
+ '<Entity[^>]*?value="([^"]*)"[^>]*/>', '\1', 'g'),
+ '\[([^\]]*)\]\([^)]*\)', '\1', 'g'),
+ 'https?://[^[:space:])>\]]+', ' ', 'g'),
+ '[*_`#>]+', ' ', 'g') as t
+ ),
+ sentences as (
+ select s.sentence, s.n
+ from clean,
+ regexp_split_to_table(clean.t, '[.!?]+[[:space:]]+|\n+') with ordinality as s(sentence, n)
+ where exists (
+ select 1 from unnest(p_names) nm
+ where length(btrim(nm)) > 0
+ and s.sentence ~* ('(^|[^[:alnum:]])'
+ || regexp_replace(btrim(nm), '([.^$*+?()\[\]{}|\\-])', '\\\1', 'g')
+ || '($|[^[:alnum:]])'))
+ ),
+ -- A phrase never spans a comma, a colon or a bracket.
+ chunks as (
+ select s.n as sn, c.chunk, c.cn
+ from sentences s,
+ regexp_split_to_table(s.sentence, '[,;:()"“”\[\]]+') with ordinality as c(chunk, cn)
+ ),
+ tokens as (
+ select ch.sn, ch.cn, w.pos, btrim(w.word, '-') as word
+ from chunks ch,
+ regexp_split_to_table(lower(ch.chunk), '[^[:alnum:]-]+') with ordinality as w(word, pos)
+ ),
+ -- Each distinct word is looked up once.
+ words as (
+ select word from (select distinct word from tokens) d
+ where length(word) >= 3
+ and word !~ '^[0-9-]+$'
+ and not (word = any (coalesce(p_exclude, '{}')))
+ and not public.mention_stopword(word)
+ ),
+ kept as (
+ select t.sn, t.cn, t.pos, t.word from tokens t join words w on w.word = t.word
+ )
+ select coalesce(array_agg(distinct term order by term), '{}')
+ from (
+ select word as term from kept
+ union all
+ select k1.word || ' ' || k2.word
+ from kept k1
+ join kept k2 on k2.sn = k1.sn and k2.cn = k1.cn and k2.pos = k1.pos + 1
+ ) t;
+$$;
+
+-- ─── Per answer and entity ──────────────────────────────────────────────────
+
+create table if not exists public.mentions_answer_terms (
+ brand_id uuid not null references public.brands(id) on delete cascade,
+ result_id uuid not null references public.prompt_results(id) on delete cascade,
+ created_at timestamptz not null,
+ prompt_id uuid not null,
+ platform text not null,
+ region text,
+ -- 'brand', or the competitor's id.
+ entity text not null,
+ terms text[] not null default '{}',
+ primary key (result_id, entity)
+);
+
+create index if not exists idx_mentions_answer_terms_brand_created
+ on public.mentions_answer_terms (brand_id, created_at);
+
+alter table public.mentions_answer_terms enable row level security;
+
+create policy "Users can read own org mention terms"
+ on public.mentions_answer_terms for select
+ using (brand_id in (
+ select b.id from public.brands b
+ join public.profiles p on p.organization_id = b.organization_id
+ where p.id = auth.uid()));
+
+-- ─── Refresh the answer terms ───────────────────────────────────────────────
+-- Recomputes the terms of a brand's answers for an inclusive UTC day range:
+-- delete + insert, as refresh_mentions_daily (00157) does for the rollups.
+-- Its own function rather than part of that refresh: reading every answer's
+-- text costs a few milliseconds per answer and entity named, seconds per day
+-- on the largest brands, and a sentiment correction (00160) refreshes the
+-- rollups inside the person's request, where terms never change. The server
+-- calls both for a completed run, the nightly sweep and the backfill
+-- (server/src/lib/mentions-rollups.js). Service-role only.
+
+create or replace function public.refresh_mention_terms(
+ p_brand_id uuid,
+ p_day_from date,
+ p_day_to date
+) returns void
+language plpgsql
+set search_path to 'public'
+as $$
+declare
+ -- The range's bounds as instants, so the answers are found by range.
+ v_from timestamptz := p_day_from::timestamp at time zone 'utc';
+ v_to timestamptz := (p_day_to + 1)::timestamp at time zone 'utc';
+begin
+ -- One refresh per brand at a time, as refresh_mentions_daily (00192): a
+ -- run's refresh and the nightly sweep can cover the same days, and the
+ -- second insert would fail on the (result_id, entity) key. The lock
+ -- releases at commit.
+ perform pg_advisory_xact_lock(
+ hashtextextended('refresh_mention_terms:' || p_brand_id::text, 0));
+
+ delete from public.mentions_answer_terms
+ where brand_id = p_brand_id and created_at >= v_from and created_at < v_to;
+
+ -- The terms next to each entity an answer names, matched by the same names
+ -- tracking counts: the brand's name and domains, each competitor's name
+ -- and domain.
+ with brand_names as (
+ select array_remove(array[b.name] || coalesce(
+ (select array_agg(bd.domain) from public.brand_domains bd where bd.brand_id = b.id),
+ '{}'), null) as names
+ from public.brands b
+ where b.id = p_brand_id
+ ),
+ competitor_names as (
+ select c.id::text as entity, array_remove(array[c.name, nullif(c.domain, '')], null) as names
+ from public.competitors c
+ where c.brand_id = p_brand_id
+ ),
+ name_words as (
+ select coalesce(array_agg(distinct w), '{}') as words
+ from (
+ select regexp_split_to_table(lower(n), '[^[:alnum:]-]+') as w
+ from (
+ select unnest(names) as n from brand_names
+ union all
+ select unnest(names) from competitor_names
+ ) all_names
+ ) split
+ where w <> ''
+ )
+ insert into public.mentions_answer_terms (
+ brand_id, result_id, created_at, prompt_id, platform, region, entity, terms)
+ select
+ p_brand_id, pr.id, pr.created_at, pr.prompt_id, pr.platform, pr.region, e.entity,
+ public.mention_terms(
+ pr.response,
+ e.names,
+ (select words from name_words) || regexp_split_to_array(lower(p.text), '[^[:alnum:]-]+'))
+ from public.prompt_results pr
+ join public.prompts p on p.id = pr.prompt_id
+ cross join lateral (
+ select 'brand'::text as entity, (select names from brand_names) as names
+ where pr.mention_count > 0
+ union all
+ select cn.entity, cn.names
+ from competitor_names cn
+ where exists (
+ select 1
+ from jsonb_array_elements(coalesce(pr.competitor_mentions, '[]'::jsonb)) cm
+ where cm.value->>'competitor_id' = cn.entity
+ and coalesce((cm.value->>'mention_count')::int, 0) > 0)
+ ) e
+ where pr.brand_id = p_brand_id
+ and pr.prompt_id is not null
+ and pr.platform <> 'chatgpt-shopping'
+ and pr.created_at >= v_from
+ and pr.created_at < v_to;
+end;
+$$;
+
+revoke execute on function public.refresh_mention_terms(uuid, date, date)
+ from public, anon, authenticated;
+
+-- ─── Read ───────────────────────────────────────────────────────────────────
+-- The Perception tab's figures for a window and the window of the same length
+-- before it (mentions_list's window, 00158: the exact instants under two
+-- days, whole UTC days otherwise). jsonb:
+-- window { from, to, days }
+-- entities the brand, then up to four competitors by mentions:
+-- { entity, name, is_brand, mentions, prev_mentions }
+-- brand_terms the brand's 15 top terms: { term, answers, prev_answers }
+-- attributes the 8 terms that tell those entities apart most (the widest
+-- spread of shares of mentions): { term, values: [{ entity, answers }] }
+-- A word that nearly always comes in one phrase is listed as that phrase.
+-- co_mentions every competitor named in the same answers as the brand:
+-- { competitor_id, name, co_mentions, prev_co_mentions }
+-- Filters: platform, region, topic, and the prompt-text search.
+
+create or replace function public.mentions_perception(
+ p_brand_id uuid,
+ p_date_from timestamptz,
+ p_date_to timestamptz default null,
+ p_platform text default null,
+ p_region text default null,
+ p_topic_id uuid default null,
+ p_search text default null
+)
+returns jsonb
+language plpgsql
+stable
+security definer
+set search_path to 'public'
+set work_mem to '64MB'
+set plan_cache_mode to 'force_custom_plan'
+as $$
+declare
+ v_to timestamptz := coalesce(p_date_to, now());
+ v_from timestamptz := least(p_date_from, coalesce(p_date_to, now()));
+ v_days integer;
+ v_day_to date;
+ v_start timestamptz;
+ v_end timestamptz;
+ v_prev_start timestamptz;
+ v_search text := nullif(btrim(lower(coalesce(p_search, ''))), '');
+ v_result jsonb;
+begin
+ if auth.role() is distinct from 'service_role' and not exists (
+ select 1 from public.brands b
+ join public.profiles pf on pf.organization_id = b.organization_id
+ where b.id = p_brand_id and pf.id = auth.uid()
+ ) then
+ return null;
+ end if;
+
+ v_days := greatest(1, ceil(extract(epoch from v_to - v_from) / 86400.0 - 1.0 / 24)::integer);
+ if v_days < 2 then
+ v_start := v_from;
+ v_end := v_to + interval '1 microsecond';
+ else
+ v_day_to := (v_to at time zone 'utc')::date;
+ v_start := (v_day_to - (v_days - 1))::timestamp at time zone 'utc';
+ v_end := (v_day_to + 1)::timestamp at time zone 'utc';
+ end if;
+ v_prev_start := v_start - (v_end - v_start);
+
+ with
+ prompts_in as (
+ select p.id
+ from public.prompts p
+ join public.prompt_sets ps on ps.id = p.prompt_set_id
+ where ps.brand_id = p_brand_id
+ and (p_topic_id is null or p.topic_id = p_topic_id)
+ and (v_search is null or position(v_search in lower(p.text)) > 0)
+ ),
+ rows_in as (
+ select t.result_id, t.entity, t.terms, (t.created_at >= v_start) as cur
+ from public.mentions_answer_terms t
+ join prompts_in pi on pi.id = t.prompt_id
+ where t.brand_id = p_brand_id
+ and t.created_at >= v_prev_start
+ and t.created_at < v_end
+ and (p_platform is null or t.platform = p_platform)
+ and (p_region is null or t.region = p_region)
+ ),
+ entity_counts as (
+ select entity,
+ count(*) filter (where cur) as mentions,
+ count(*) filter (where not cur) as prev_mentions
+ from rows_in
+ group by entity
+ ),
+ shown as (
+ select 'brand'::text as entity, 0 as rank
+ union all
+ select * from (
+ select ec.entity, row_number() over (order by ec.mentions desc, ec.entity)::int
+ from entity_counts ec
+ join public.competitors co on co.id::text = ec.entity and co.brand_id = p_brand_id
+ where ec.mentions > 0
+ order by ec.mentions desc, ec.entity
+ limit 4
+ ) top_competitors
+ ),
+ term_counts_all as (
+ select r.entity, term,
+ count(*) filter (where r.cur) as answers,
+ count(*) filter (where not r.cur) as prev_answers
+ from rows_in r
+ join shown s on s.entity = r.entity
+ cross join lateral unnest(r.terms) as term
+ group by r.entity, term
+ ),
+ -- Each entity's 60 most frequent terms are the candidates.
+ candidates as (
+ select entity, term, answers, prev_answers
+ from (
+ select t.*, row_number() over (partition by t.entity order by t.answers desc, t.term) as rn
+ from term_counts_all t
+ where t.answers > 0
+ ) ranked
+ where rn <= 60
+ ),
+ -- A word that nearly always comes in one phrase is that phrase: "fresh" and
+ -- "roast" give way to "fresh roast" when it has 80% of their answers.
+ term_counts as (
+ select c.*
+ from candidates c
+ where position(' ' in c.term) > 0
+ or not exists (
+ select 1 from candidates p
+ where p.entity = c.entity
+ and position(' ' in p.term) > 0
+ and (p.term like c.term || ' %' or p.term like '% ' || c.term)
+ and p.answers >= 0.8 * c.answers)
+ ),
+ brand_terms as (
+ select term, answers, prev_answers
+ from term_counts
+ where entity = 'brand' and answers > 0
+ order by answers desc, term
+ limit 15
+ ),
+ -- The terms that tell the brands apart most: the widest spread between the
+ -- highest and lowest share of mentions, then the highest shares.
+ attributes as (
+ select u.term
+ from (select distinct term from term_counts) u
+ cross join shown s
+ left join term_counts_all tc on tc.entity = s.entity and tc.term = u.term
+ left join entity_counts ec on ec.entity = s.entity
+ group by u.term
+ order by
+ max(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0))
+ - min(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0)) desc nulls last,
+ sum(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0)) desc nulls last,
+ u.term
+ limit 8
+ ),
+ -- A competitor's rows in answers that name the brand too, in one pass.
+ co as (
+ select x.entity,
+ count(*) filter (where x.cur) as co_mentions,
+ count(*) filter (where not x.cur) as prev_co_mentions
+ from (
+ select r.entity, r.cur,
+ bool_or(r.entity = 'brand') over (partition by r.result_id) as with_brand
+ from rows_in r
+ ) x
+ where x.entity <> 'brand' and x.with_brand
+ group by x.entity
+ )
+ select jsonb_build_object(
+ 'window', jsonb_build_object('from', v_start, 'to', v_end, 'days', v_days),
+ 'entities', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'entity', s.entity,
+ 'name', case when s.entity = 'brand' then b.name else co.name end,
+ 'is_brand', s.entity = 'brand',
+ 'mentions', coalesce(ec.mentions, 0),
+ 'prev_mentions', coalesce(ec.prev_mentions, 0))
+ order by s.rank)
+ from shown s
+ left join entity_counts ec on ec.entity = s.entity
+ left join public.brands b on s.entity = 'brand' and b.id = p_brand_id
+ left join public.competitors co on co.id::text = s.entity and co.brand_id = p_brand_id
+ ), '[]'::jsonb),
+ 'brand_terms', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'term', bt.term, 'answers', bt.answers, 'prev_answers', bt.prev_answers)
+ order by bt.answers desc, bt.term)
+ from brand_terms bt
+ ), '[]'::jsonb),
+ 'attributes', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'term', a.term,
+ 'values', (
+ select jsonb_agg(jsonb_build_object(
+ 'entity', s.entity, 'answers', coalesce(tc.answers, 0))
+ order by s.rank)
+ from shown s
+ left join term_counts_all tc on tc.entity = s.entity and tc.term = a.term)))
+ from attributes a
+ ), '[]'::jsonb),
+ 'co_mentions', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'competitor_id', c.entity,
+ 'name', comp.name,
+ 'co_mentions', c.co_mentions,
+ 'prev_co_mentions', c.prev_co_mentions)
+ order by c.co_mentions desc, comp.name)
+ from co c
+ join public.competitors comp on comp.id::text = c.entity and comp.brand_id = p_brand_id
+ ), '[]'::jsonb)
+ )
+ into v_result;
+
+ return v_result;
+end;
+$$;
+
+revoke execute on function public.mentions_perception(uuid, timestamptz, timestamptz, text, text, uuid, text)
+ from public, anon;
+grant execute on function public.mentions_perception(uuid, timestamptz, timestamptz, text, text, uuid, text)
+ to authenticated, service_role;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 795384f2c..12040783e 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -20488,6 +20488,493 @@ revoke execute on function public.override_mention_sentiment(uuid, text, text) f
grant execute on function public.override_mention_sentiment(uuid, text, text)
to authenticated, service_role;
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00161_mentions_perception.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00161: What AI associates with each brand (Mentions & Sentiment, MS-09)
+-- ============================================================================
+-- The Perception tab asks what AI says next to a brand: the terms around its
+-- mentions, how they compare with the competitors', and which competitors AI
+-- names beside it. Spec §9 wants it deterministic in V1 (no LLM): the terms
+-- come from the stored answers' text by rule.
+--
+-- * mention_terms(text, names, exclude) takes the sentences that name an
+-- entity (a whole word, ignoring case) and returns their words and
+-- two-word phrases, minus stop words in the languages tracked (Postgres'
+-- Snowball dictionaries), a short list of words answers use about every
+-- brand alike, and the words in `exclude`: every brand's and competitor's
+-- names, and the question's own words (they would rank first for every
+-- brand and say nothing about it). A phrase never spans a comma or a
+-- bracket.
+-- * mentions_answer_terms keeps, per answer and per entity it names (the
+-- brand, or a competitor by id), the distinct terms. One row per answer
+-- and entity, not per term per day: the page's filters (topic, search,
+-- platform, country) and the window before stay available, and the table
+-- grows with the answers, not with the vocabulary.
+-- * refresh_mention_terms fills it for a UTC day range. The server calls it
+-- beside refresh_mentions_daily (00157), for the same days and callers: a
+-- completed run, the nightly sweep and backfill-mentions-daily.js. A
+-- sentiment correction (00160) refreshes only the rollups.
+-- * mentions_perception(...) reads a window and the one before it: the
+-- brand's top terms with their trend, the attributes that tell the brand
+-- and its four most mentioned competitors apart, with each one's share
+-- of mentions, and the competitors named in the same answers as the
+-- brand, now and before.
+--
+-- Terms describe what is said next to a brand, not who it is said about: a
+-- sentence naming two brands lends its words to both. Spec §3 leaves themes
+-- and polarity to the V1.5 classifier.
+
+-- ─── Terms ──────────────────────────────────────────────────────────────────
+
+create or replace function public.mention_stopword(p_word text)
+returns boolean
+language sql
+stable
+parallel safe
+set search_path to 'public', 'pg_catalog'
+as $$
+ select p_word = any (array[
+ 'best', 'top', 'also', 'like', 'well', 'great', 'good', 'better', 'many', 'much',
+ 'more', 'most', 'other', 'others', 'one', 'two', 'three', 'first', 'second',
+ 'third', 'new', 'known', 'popular', 'option', 'options', 'choice', 'choices',
+ 'alternative', 'alternatives', 'include', 'includes', 'including', 'offer',
+ 'offers', 'offering', 'provide', 'provides', 'providing', 'list', 'lists',
+ 'brand', 'brands', 'company', 'companies', 'service', 'services', 'product',
+ 'products', 'platform', 'platforms', 'tool', 'tools', 'solution', 'solutions',
+ 'feature', 'features', 'use', 'used', 'using', 'user', 'users', 'customer',
+ 'customers', 'help', 'helps', 'make', 'makes', 'get', 'gets', 'often',
+ 'especially', 'consider', 'considered', 'overall', 'recommend', 'recommended',
+ 'highly', 'rated', 'review', 'reviews', 'www', 'com', 'http', 'https', 'etc',
+ 'whether', 'however', 'although', 'though', 'still', 'even', 'just', 'really',
+ 'various', 'several', 'number', 'way', 'ways', 'thing', 'things', 'look',
+ 'looking', 'want', 'need', 'needs', 'depending', 'depends', 'based', 'pick',
+ 'picks', 'stand', 'stands', 'out', 'here', 'there', 'below', 'above',
+ -- Where a brand sits in a list, not what it is.
+ 'ahead', 'behind', 'leads', 'lead', 'leading', 'comes', 'come', 'close',
+ 'closely', 'rank', 'ranks', 'ranked', 'spot', 'place', 'placed', 'followed',
+ 'follows', 'next', 'usual',
+ -- How answers talk about anything.
+ 'solid', 'say', 'says', 'said', 'buyer', 'buyers', 'people', 'focus', 'focuses',
+ 'focused', 'mention', 'mentions', 'mentioned', 'reviewer', 'reviewers', 'start',
+ 'starts', 'starting', 'wants', 'worth', 'available'])
+ or ts_lexize('english_stem', p_word) = '{}'
+ or ts_lexize('german_stem', p_word) = '{}'
+ or ts_lexize('french_stem', p_word) = '{}'
+ or ts_lexize('spanish_stem', p_word) = '{}'
+ or ts_lexize('italian_stem', p_word) = '{}'
+ or ts_lexize('portuguese_stem', p_word) = '{}'
+ or ts_lexize('dutch_stem', p_word) = '{}'
+ or ts_lexize('turkish_stem', p_word) = '{}'
+ or ts_lexize('swedish_stem', p_word) = '{}'
+ or ts_lexize('danish_stem', p_word) = '{}'
+ or ts_lexize('norwegian_stem', p_word) = '{}'
+ or ts_lexize('finnish_stem', p_word) = '{}'
+ or ts_lexize('russian_stem', p_word) = '{}';
+$$;
+
+create or replace function public.mention_terms(p_text text, p_names text[], p_exclude text[])
+returns text[]
+language sql
+stable
+parallel safe
+set search_path to 'public', 'pg_catalog'
+as $$
+ with clean as (
+ -- ChatGPT's entity tags read as their names, links as their labels, bare
+ -- URLs and markdown marks dropped.
+ select regexp_replace(regexp_replace(regexp_replace(regexp_replace(coalesce(p_text, ''),
+ '<Entity[^>]*?value="([^"]*)"[^>]*/>', '\1', 'g'),
+ '\[([^\]]*)\]\([^)]*\)', '\1', 'g'),
+ 'https?://[^[:space:])>\]]+', ' ', 'g'),
+ '[*_`#>]+', ' ', 'g') as t
+ ),
+ sentences as (
+ select s.sentence, s.n
+ from clean,
+ regexp_split_to_table(clean.t, '[.!?]+[[:space:]]+|\n+') with ordinality as s(sentence, n)
+ where exists (
+ select 1 from unnest(p_names) nm
+ where length(btrim(nm)) > 0
+ and s.sentence ~* ('(^|[^[:alnum:]])'
+ || regexp_replace(btrim(nm), '([.^$*+?()\[\]{}|\\-])', '\\\1', 'g')
+ || '($|[^[:alnum:]])'))
+ ),
+ -- A phrase never spans a comma, a colon or a bracket.
+ chunks as (
+ select s.n as sn, c.chunk, c.cn
+ from sentences s,
+ regexp_split_to_table(s.sentence, '[,;:()"“”\[\]]+') with ordinality as c(chunk, cn)
+ ),
+ tokens as (
+ select ch.sn, ch.cn, w.pos, btrim(w.word, '-') as word
+ from chunks ch,
+ regexp_split_to_table(lower(ch.chunk), '[^[:alnum:]-]+') with ordinality as w(word, pos)
+ ),
+ -- Each distinct word is looked up once.
+ words as (
+ select word from (select distinct word from tokens) d
+ where length(word) >= 3
+ and word !~ '^[0-9-]+$'
+ and not (word = any (coalesce(p_exclude, '{}')))
+ and not public.mention_stopword(word)
+ ),
+ kept as (
+ select t.sn, t.cn, t.pos, t.word from tokens t join words w on w.word = t.word
+ )
+ select coalesce(array_agg(distinct term order by term), '{}')
+ from (
+ select word as term from kept
+ union all
+ select k1.word || ' ' || k2.word
+ from kept k1
+ join kept k2 on k2.sn = k1.sn and k2.cn = k1.cn and k2.pos = k1.pos + 1
+ ) t;
+$$;
+
+-- ─── Per answer and entity ──────────────────────────────────────────────────
+
+create table if not exists public.mentions_answer_terms (
+ brand_id uuid not null references public.brands(id) on delete cascade,
+ result_id uuid not null references public.prompt_results(id) on delete cascade,
+ created_at timestamptz not null,
+ prompt_id uuid not null,
+ platform text not null,
+ region text,
+ -- 'brand', or the competitor's id.
+ entity text not null,
+ terms text[] not null default '{}',
+ primary key (result_id, entity)
+);
+
+create index if not exists idx_mentions_answer_terms_brand_created
+ on public.mentions_answer_terms (brand_id, created_at);
+
+alter table public.mentions_answer_terms enable row level security;
+
+create policy "Users can read own org mention terms"
+ on public.mentions_answer_terms for select
+ using (brand_id in (
+ select b.id from public.brands b
+ join public.profiles p on p.organization_id = b.organization_id
+ where p.id = auth.uid()));
+
+-- ─── Refresh the answer terms ───────────────────────────────────────────────
+-- Recomputes the terms of a brand's answers for an inclusive UTC day range:
+-- delete + insert, as refresh_mentions_daily (00157) does for the rollups.
+-- Its own function rather than part of that refresh: reading every answer's
+-- text costs a few milliseconds per answer and entity named, seconds per day
+-- on the largest brands, and a sentiment correction (00160) refreshes the
+-- rollups inside the person's request, where terms never change. The server
+-- calls both for a completed run, the nightly sweep and the backfill
+-- (server/src/lib/mentions-rollups.js). Service-role only.
+
+create or replace function public.refresh_mention_terms(
+ p_brand_id uuid,
+ p_day_from date,
+ p_day_to date
+) returns void
+language plpgsql
+set search_path to 'public'
+as $$
+declare
+ -- The range's bounds as instants, so the answers are found by range.
+ v_from timestamptz := p_day_from::timestamp at time zone 'utc';
+ v_to timestamptz := (p_day_to + 1)::timestamp at time zone 'utc';
+begin
+ -- One refresh per brand at a time, as refresh_mentions_daily (00192): a
+ -- run's refresh and the nightly sweep can cover the same days, and the
+ -- second insert would fail on the (result_id, entity) key. The lock
+ -- releases at commit.
+ perform pg_advisory_xact_lock(
+ hashtextextended('refresh_mention_terms:' || p_brand_id::text, 0));
+
+ delete from public.mentions_answer_terms
+ where brand_id = p_brand_id and created_at >= v_from and created_at < v_to;
+
+ -- The terms next to each entity an answer names, matched by the same names
+ -- tracking counts: the brand's name and domains, each competitor's name
+ -- and domain.
+ with brand_names as (
+ select array_remove(array[b.name] || coalesce(
+ (select array_agg(bd.domain) from public.brand_domains bd where bd.brand_id = b.id),
+ '{}'), null) as names
+ from public.brands b
+ where b.id = p_brand_id
+ ),
+ competitor_names as (
+ select c.id::text as entity, array_remove(array[c.name, nullif(c.domain, '')], null) as names
+ from public.competitors c
+ where c.brand_id = p_brand_id
+ ),
+ name_words as (
+ select coalesce(array_agg(distinct w), '{}') as words
+ from (
+ select regexp_split_to_table(lower(n), '[^[:alnum:]-]+') as w
+ from (
+ select unnest(names) as n from brand_names
+ union all
+ select unnest(names) from competitor_names
+ ) all_names
+ ) split
+ where w <> ''
+ )
+ insert into public.mentions_answer_terms (
+ brand_id, result_id, created_at, prompt_id, platform, region, entity, terms)
+ select
+ p_brand_id, pr.id, pr.created_at, pr.prompt_id, pr.platform, pr.region, e.entity,
+ public.mention_terms(
+ pr.response,
+ e.names,
+ (select words from name_words) || regexp_split_to_array(lower(p.text), '[^[:alnum:]-]+'))
+ from public.prompt_results pr
+ join public.prompts p on p.id = pr.prompt_id
+ cross join lateral (
+ select 'brand'::text as entity, (select names from brand_names) as names
+ where pr.mention_count > 0
+ union all
+ select cn.entity, cn.names
+ from competitor_names cn
+ where exists (
+ select 1
+ from jsonb_array_elements(coalesce(pr.competitor_mentions, '[]'::jsonb)) cm
+ where cm.value->>'competitor_id' = cn.entity
+ and coalesce((cm.value->>'mention_count')::int, 0) > 0)
+ ) e
+ where pr.brand_id = p_brand_id
+ and pr.prompt_id is not null
+ and pr.platform <> 'chatgpt-shopping'
+ and pr.created_at >= v_from
+ and pr.created_at < v_to;
+end;
+$$;
+
+revoke execute on function public.refresh_mention_terms(uuid, date, date)
+ from public, anon, authenticated;
+
+-- ─── Read ───────────────────────────────────────────────────────────────────
+-- The Perception tab's figures for a window and the window of the same length
+-- before it (mentions_list's window, 00158: the exact instants under two
+-- days, whole UTC days otherwise). jsonb:
+-- window { from, to, days }
+-- entities the brand, then up to four competitors by mentions:
+-- { entity, name, is_brand, mentions, prev_mentions }
+-- brand_terms the brand's 15 top terms: { term, answers, prev_answers }
+-- attributes the 8 terms that tell those entities apart most (the widest
+-- spread of shares of mentions): { term, values: [{ entity, answers }] }
+-- A word that nearly always comes in one phrase is listed as that phrase.
+-- co_mentions every competitor named in the same answers as the brand:
+-- { competitor_id, name, co_mentions, prev_co_mentions }
+-- Filters: platform, region, topic, and the prompt-text search.
+
+create or replace function public.mentions_perception(
+ p_brand_id uuid,
+ p_date_from timestamptz,
+ p_date_to timestamptz default null,
+ p_platform text default null,
+ p_region text default null,
+ p_topic_id uuid default null,
+ p_search text default null
+)
+returns jsonb
+language plpgsql
+stable
+security definer
+set search_path to 'public'
+set work_mem to '64MB'
+set plan_cache_mode to 'force_custom_plan'
+as $$
+declare
+ v_to timestamptz := coalesce(p_date_to, now());
+ v_from timestamptz := least(p_date_from, coalesce(p_date_to, now()));
+ v_days integer;
+ v_day_to date;
+ v_start timestamptz;
+ v_end timestamptz;
+ v_prev_start timestamptz;
+ v_search text := nullif(btrim(lower(coalesce(p_search, ''))), '');
+ v_result jsonb;
+begin
+ if auth.role() is distinct from 'service_role' and not exists (
+ select 1 from public.brands b
+ join public.profiles pf on pf.organization_id = b.organization_id
+ where b.id = p_brand_id and pf.id = auth.uid()
+ ) then
+ return null;
+ end if;
+
+ v_days := greatest(1, ceil(extract(epoch from v_to - v_from) / 86400.0 - 1.0 / 24)::integer);
+ if v_days < 2 then
+ v_start := v_from;
+ v_end := v_to + interval '1 microsecond';
+ else
+ v_day_to := (v_to at time zone 'utc')::date;
+ v_start := (v_day_to - (v_days - 1))::timestamp at time zone 'utc';
+ v_end := (v_day_to + 1)::timestamp at time zone 'utc';
+ end if;
+ v_prev_start := v_start - (v_end - v_start);
+
+ with
+ prompts_in as (
+ select p.id
+ from public.prompts p
+ join public.prompt_sets ps on ps.id = p.prompt_set_id
+ where ps.brand_id = p_brand_id
+ and (p_topic_id is null or p.topic_id = p_topic_id)
+ and (v_search is null or position(v_search in lower(p.text)) > 0)
+ ),
+ rows_in as (
+ select t.result_id, t.entity, t.terms, (t.created_at >= v_start) as cur
+ from public.mentions_answer_terms t
+ join prompts_in pi on pi.id = t.prompt_id
+ where t.brand_id = p_brand_id
+ and t.created_at >= v_prev_start
+ and t.created_at < v_end
+ and (p_platform is null or t.platform = p_platform)
+ and (p_region is null or t.region = p_region)
+ ),
+ entity_counts as (
+ select entity,
+ count(*) filter (where cur) as mentions,
+ count(*) filter (where not cur) as prev_mentions
+ from rows_in
+ group by entity
+ ),
+ shown as (
+ select 'brand'::text as entity, 0 as rank
+ union all
+ select * from (
+ select ec.entity, row_number() over (order by ec.mentions desc, ec.entity)::int
+ from entity_counts ec
+ join public.competitors co on co.id::text = ec.entity and co.brand_id = p_brand_id
+ where ec.mentions > 0
+ order by ec.mentions desc, ec.entity
+ limit 4
+ ) top_competitors
+ ),
+ term_counts_all as (
+ select r.entity, term,
+ count(*) filter (where r.cur) as answers,
+ count(*) filter (where not r.cur) as prev_answers
+ from rows_in r
+ join shown s on s.entity = r.entity
+ cross join lateral unnest(r.terms) as term
+ group by r.entity, term
+ ),
+ -- Each entity's 60 most frequent terms are the candidates.
+ candidates as (
+ select entity, term, answers, prev_answers
+ from (
+ select t.*, row_number() over (partition by t.entity order by t.answers desc, t.term) as rn
+ from term_counts_all t
+ where t.answers > 0
+ ) ranked
+ where rn <= 60
+ ),
+ -- A word that nearly always comes in one phrase is that phrase: "fresh" and
+ -- "roast" give way to "fresh roast" when it has 80% of their answers.
+ term_counts as (
+ select c.*
+ from candidates c
+ where position(' ' in c.term) > 0
+ or not exists (
+ select 1 from candidates p
+ where p.entity = c.entity
+ and position(' ' in p.term) > 0
+ and (p.term like c.term || ' %' or p.term like '% ' || c.term)
+ and p.answers >= 0.8 * c.answers)
+ ),
+ brand_terms as (
+ select term, answers, prev_answers
+ from term_counts
+ where entity = 'brand' and answers > 0
+ order by answers desc, term
+ limit 15
+ ),
+ -- The terms that tell the brands apart most: the widest spread between the
+ -- highest and lowest share of mentions, then the highest shares.
+ attributes as (
+ select u.term
+ from (select distinct term from term_counts) u
+ cross join shown s
+ left join term_counts_all tc on tc.entity = s.entity and tc.term = u.term
+ left join entity_counts ec on ec.entity = s.entity
+ group by u.term
+ order by
+ max(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0))
+ - min(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0)) desc nulls last,
+ sum(coalesce(tc.answers, 0)::numeric / nullif(ec.mentions, 0)) desc nulls last,
+ u.term
+ limit 8
+ ),
+ -- A competitor's rows in answers that name the brand too, in one pass.
+ co as (
+ select x.entity,
+ count(*) filter (where x.cur) as co_mentions,
+ count(*) filter (where not x.cur) as prev_co_mentions
+ from (
+ select r.entity, r.cur,
+ bool_or(r.entity = 'brand') over (partition by r.result_id) as with_brand
+ from rows_in r
+ ) x
+ where x.entity <> 'brand' and x.with_brand
+ group by x.entity
+ )
+ select jsonb_build_object(
+ 'window', jsonb_build_object('from', v_start, 'to', v_end, 'days', v_days),
+ 'entities', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'entity', s.entity,
+ 'name', case when s.entity = 'brand' then b.name else co.name end,
+ 'is_brand', s.entity = 'brand',
+ 'mentions', coalesce(ec.mentions, 0),
+ 'prev_mentions', coalesce(ec.prev_mentions, 0))
+ order by s.rank)
+ from shown s
+ left join entity_counts ec on ec.entity = s.entity
+ left join public.brands b on s.entity = 'brand' and b.id = p_brand_id
+ left join public.competitors co on co.id::text = s.entity and co.brand_id = p_brand_id
+ ), '[]'::jsonb),
+ 'brand_terms', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'term', bt.term, 'answers', bt.answers, 'prev_answers', bt.prev_answers)
+ order by bt.answers desc, bt.term)
+ from brand_terms bt
+ ), '[]'::jsonb),
+ 'attributes', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'term', a.term,
+ 'values', (
+ select jsonb_agg(jsonb_build_object(
+ 'entity', s.entity, 'answers', coalesce(tc.answers, 0))
+ order by s.rank)
+ from shown s
+ left join term_counts_all tc on tc.entity = s.entity and tc.term = a.term)))
+ from attributes a
+ ), '[]'::jsonb),
+ 'co_mentions', coalesce((
+ select jsonb_agg(jsonb_build_object(
+ 'competitor_id', c.entity,
+ 'name', comp.name,
+ 'co_mentions', c.co_mentions,
+ 'prev_co_mentions', c.prev_co_mentions)
+ order by c.co_mentions desc, comp.name)
+ from co c
+ join public.competitors comp on comp.id::text = c.entity and comp.brand_id = p_brand_id
+ ), '[]'::jsonb)
+ )
+ into v_result;
+
+ return v_result;
+end;
+$$;
+
+revoke execute on function public.mentions_perception(uuid, timestamptz, timestamptz, text, text, uuid, text)
+ from public, anon;
+grant execute on function public.mentions_perception(uuid, timestamptz, timestamptz, text, text, uuid, text)
+ to authenticated, service_role;
+
-- ─────────────────────────────────────────────────────────────────────────
-- migrations/00162_refresh_insights_daily_range.sql
-- ─────────────────────────────────────────────────────────────────────────
diff --git a/web/src/lib/actions/mentions.test.ts b/web/src/lib/actions/mentions.test.ts
index 206b75b46..a63bd884c 100644
--- a/web/src/lib/actions/mentions.test.ts
+++ b/web/src/lib/actions/mentions.test.ts
@@ -32,6 +32,7 @@ import {
exportMentions,
getMentionResponse,
getMentionsOverview,
+ getMentionsPerception,
listMentions,
overrideMentionSentiment,
sendMentionsToActionCenter,
@@ -411,3 +412,40 @@ describe('sendMentionsToActionCenter', () => {
});
});
});
+
+describe('getMentionsPerception', () => {
+ it('reads the window and filters in one call', async () => {
+ result = {
+ data: {
+ window: { from: 'f', to: 't', days: 30 },
+ entities: [{ entity: 'brand', name: 'Acme', is_brand: true, mentions: 10 }],
+ brand_terms: [],
+ attributes: [],
+ co_mentions: [],
+ },
+ error: null,
+ };
+ const perception = await getMentionsPerception('b1', {
+ from: '2026-10-10T00:00:00.000Z',
+ region: 'DE',
+ search: 'beans',
+ });
+ expect(rpc).toHaveBeenCalledWith('mentions_perception', {
+ p_brand_id: 'b1',
+ p_date_from: '2026-10-10T00:00:00.000Z',
+ p_date_to: undefined,
+ p_platform: undefined,
+ p_region: 'DE',
+ p_topic_id: undefined,
+ p_search: 'beans',
+ });
+ expect(perception?.entities[0]).toMatchObject({ name: 'Acme', isBrand: true, mentions: 10 });
+ });
+
+ it('is null before the migration has run, and throws on other errors', async () => {
+ result = { data: null, error: { code: 'PGRST202', message: 'not found' } };
+ await expect(getMentionsPerception('b1', { from: 'f' })).resolves.toBeNull();
+ result = { data: null, error: { code: '57014', message: 'statement timeout' } };
+ await expect(getMentionsPerception('b1', { from: 'f' })).rejects.toThrow('statement timeout');
+ });
+});
diff --git a/web/src/lib/actions/mentions.ts b/web/src/lib/actions/mentions.ts
index 19ea4622b..d5ab5e9be 100644
--- a/web/src/lib/actions/mentions.ts
+++ b/web/src/lib/actions/mentions.ts
@@ -15,6 +15,7 @@ import {
type SentimentOverride,
} from '@/lib/mentions-list';
import { parseMentionsOverview, type MentionsOverview } from '@/lib/mentions-overview';
+import { parseMentionsPerception, type MentionsPerception } from '@/lib/mentions-perception';
import type { Citation } from '@/types';
/**
@@ -275,3 +276,29 @@ export async function sendMentionsToActionCenter(
}
return res.json();
}
+
+/**
+ * The Perception tab's figures (MS-09) for a window and the window before it,
+ * from the per-answer terms (00161): the brand's terms, the attributes that
+ * tell it and its competitors apart, and the competitors named beside it.
+ *
+ * Null as getMentionsOverview: no function yet (PGRST202), or no access.
+ */
+export async function getMentionsPerception(
+ brandId: string,
+ query: MentionsQuery,
+): Promise<MentionsPerception | null> {
+ const supabase = await createClient();
+ const { data, error } = await supabase.rpc('mentions_perception', {
+ p_brand_id: brandId,
+ p_date_from: query.from,
+ p_date_to: query.to,
+ p_platform: query.platform,
+ p_region: query.region,
+ p_topic_id: query.topicId,
+ p_search: query.search,
+ });
+ if (error?.code === 'PGRST202') return null;
+ if (error) throw new Error(error.message);
+ return parseMentionsPerception(data);
+}
diff --git a/web/src/lib/mentions-perception.test.ts b/web/src/lib/mentions-perception.test.ts
new file mode 100644
index 000000000..f57263f6e
--- /dev/null
+++ b/web/src/lib/mentions-perception.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import {
+ attributeShares,
+ biggestGap,
+ changeOf,
+ parseMentionsPerception,
+ shareOf,
+ type MentionsPerception,
+} from './mentions-perception';
+
+const raw = {
+ window: { from: '2026-09-18T00:00:00Z', to: '2026-10-18T00:00:00Z', days: 30 },
+ entities: [
+ { entity: 'brand', name: 'Acme Coffee', is_brand: true, mentions: 100, prev_mentions: 80 },
+ { entity: 'c1', name: 'Crema Club', is_brand: false, mentions: 50, prev_mentions: 40 },
+ { entity: 'c2', name: 'Origin Box', is_brand: false, mentions: 0, prev_mentions: 5 },
+ ],
+ brand_terms: [{ term: 'fresh roast', answers: 75, prev_answers: 60 }],
+ attributes: [
+ {
+ term: 'fast delivery',
+ values: [
+ { entity: 'brand', answers: 0 },
+ { entity: 'c1', answers: 30 },
+ { entity: 'c2', answers: 0 },
+ ],
+ },
+ {
+ term: 'fresh roast',
+ values: [
+ { entity: 'brand', answers: 75 },
+ { entity: 'c1', answers: 10 },
+ { entity: 'c2', answers: 0 },
+ ],
+ },
+ ],
+ co_mentions: [{ competitor_id: 'c1', name: 'Crema Club', co_mentions: 40, prev_co_mentions: 30 }],
+};
+
+describe('parseMentionsPerception', () => {
+ it("maps the function's jsonb to the page's shape", () => {
+ const p = parseMentionsPerception(raw)!;
+ expect(p.window.days).toBe(30);
+ expect(p.entities[0]).toEqual({
+ entity: 'brand',
+ name: 'Acme Coffee',
+ isBrand: true,
+ mentions: 100,
+ previousMentions: 80,
+ });
+ expect(p.brandTerms).toEqual([{ term: 'fresh roast', answers: 75, previousAnswers: 60 }]);
+ expect(p.attributes[0].values[1]).toEqual({ entity: 'c1', answers: 30 });
+ expect(p.coMentions).toEqual([
+ { competitorId: 'c1', name: 'Crema Club', coMentions: 40, previousCoMentions: 30 },
+ ]);
+ });
+
+ it('is null when there is nothing to read, and empty lists stay empty', () => {
+ expect(parseMentionsPerception(null)).toBeNull();
+ expect(parseMentionsPerception({})).toEqual({
+ window: { from: '', to: '', days: 0 },
+ entities: [],
+ brandTerms: [],
+ attributes: [],
+ coMentions: [],
+ });
+ });
+});
+
+describe('shares and changes', () => {
+ it('takes shares over mentions, and changes over the window before', () => {
+ expect(shareOf(7, 50)).toBe(14);
+ expect(shareOf(3, 0)).toBeNull();
+ expect(changeOf(75, 60)).toBe(25);
+ expect(changeOf(5, 0)).toBeNull();
+ });
+
+ it("gives each attribute's share per entity, null without mentions", () => {
+ expect(attributeShares(parseMentionsPerception(raw)!)).toEqual([
+ { term: 'fast delivery', shares: [0, 60, null] },
+ { term: 'fresh roast', shares: [75, 20, null] },
+ ]);
+ });
+});
+
+describe('biggestGap', () => {
+ it('finds the attribute a competitor leads by the widest margin', () => {
+ expect(biggestGap(parseMentionsPerception(raw)!)).toEqual({
+ term: 'fast delivery',
+ competitor: 'Crema Club',
+ competitorShare: 60,
+ brandShare: 0,
+ brandRank: null,
+ });
+ });
+
+ it('ranks the brand when AI uses the term for it too', () => {
+ const p: MentionsPerception = {
+ ...parseMentionsPerception(raw)!,
+ attributes: [
+ {
+ term: 'integrations',
+ values: [
+ { entity: 'brand', answers: 10 },
+ { entity: 'c1', answers: 40 },
+ ],
+ },
+ ],
+ };
+ expect(biggestGap(p)).toMatchObject({ competitorShare: 80, brandShare: 10, brandRank: 2 });
+ });
+
+ it('is null when no competitor leads by 20 points', () => {
+ const p: MentionsPerception = {
+ ...parseMentionsPerception(raw)!,
+ attributes: [
+ {
+ term: 'organic',
+ values: [
+ { entity: 'brand', answers: 40 },
+ { entity: 'c1', answers: 25 },
+ ],
+ },
+ ],
+ };
+ expect(biggestGap(p)).toBeNull();
+ });
+});
diff --git a/web/src/lib/mentions-perception.ts b/web/src/lib/mentions-perception.ts
new file mode 100644
index 000000000..bcc295a90
--- /dev/null
+++ b/web/src/lib/mentions-perception.ts
@@ -0,0 +1,159 @@
+import { relativeChange } from '@/lib/mentions-overview';
+
+/**
+ * The Mentions & Sentiment Perception tab's figures (MS-09), as
+ * mentions_perception (00161) returns them for a window and the one before
+ * it: the terms AI uses next to the brand, the attributes that tell it and
+ * its competitors apart, and the competitors named beside it. Terms come
+ * from the answers by rule (spec §9, V1: no LLM): they describe what is said
+ * next to a brand, so a sentence naming two brands lends its words to both.
+ */
+
+export interface PerceptionEntity {
+ /** 'brand', or a competitor's id. */
+ entity: string;
+ name: string;
+ isBrand: boolean;
+ /** Answers naming it in the window, and in the window before. */
+ mentions: number;
+ previousMentions: number;
+}
+
+export interface PerceptionTerm {
+ term: string;
+ /** Answers naming the brand with the term next to it. */
+ answers: number;
+ previousAnswers: number;
+}
+
+export interface PerceptionAttribute {
+ term: string;
+ /** Per entity, in the entities' order: answers naming it with the term next to it. */
+ values: { entity: string; answers: number }[];
+}
+
+export interface PerceptionCoMention {
+ competitorId: string;
+ name: string;
+ /** Answers naming the competitor and the brand, now and before. */
+ coMentions: number;
+ previousCoMentions: number;
+}
+
+export interface MentionsPerception {
+ window: { from: string; to: string; days: number };
+ /** The brand first, then up to four competitors by mentions. */
+ entities: PerceptionEntity[];
+ brandTerms: PerceptionTerm[];
+ attributes: PerceptionAttribute[];
+ coMentions: PerceptionCoMention[];
+}
+
+type Raw = Record<string, unknown>;
+const num = (r: Raw | undefined, key: string): number => Number(r?.[key] ?? 0) || 0;
+const rows = (value: unknown): Raw[] => (Array.isArray(value) ? (value as Raw[]) : []);
+
+/** The function's jsonb as the page's shape; null when there is nothing to read. */
+export function parseMentionsPerception(raw: unknown): MentionsPerception | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const r = raw as Raw;
+ const w = (r.window ?? {}) as Raw;
+ return {
+ window: { from: String(w.from ?? ''), to: String(w.to ?? ''), days: num(w, 'days') },
+ entities: rows(r.entities).map((e) => ({
+ entity: String(e.entity ?? ''),
+ name: String(e.name ?? ''),
+ isBrand: e.is_brand === true,
+ mentions: num(e, 'mentions'),
+ previousMentions: num(e, 'prev_mentions'),
+ })),
+ brandTerms: rows(r.brand_terms).map((t) => ({
+ term: String(t.term ?? ''),
+ answers: num(t, 'answers'),
+ previousAnswers: num(t, 'prev_answers'),
+ })),
+ attributes: rows(r.attributes).map((a) => ({
+ term: String(a.term ?? ''),
+ values: rows(a.values).map((v) => ({
+ entity: String(v.entity ?? ''),
+ answers: num(v, 'answers'),
+ })),
+ })),
+ coMentions: rows(r.co_mentions).map((c) => ({
+ competitorId: String(c.competitor_id ?? ''),
+ name: String(c.name ?? ''),
+ coMentions: num(c, 'co_mentions'),
+ previousCoMentions: num(c, 'prev_co_mentions'),
+ })),
+ };
+}
+
+/** A count as a percentage of the mentions it is taken over; null with none. */
+export function shareOf(answers: number, mentions: number): number | null {
+ // Multiplied first, so whole percentages stay whole.
+ return mentions > 0 ? (answers * 100) / mentions : null;
+}
+
+/** A term's or co-mention's change against the window before, in percent. */
+export function changeOf(now: number, before: number): number | null {
+ return relativeChange(now, before);
+}
+
+/**
+ * Each attribute's share of each entity's mentions, in the entities' order:
+ * the heat map's cells and the radar's points. Null where an entity has no
+ * mentions to take a share over.
+ */
+export function attributeShares(
+ p: Pick<MentionsPerception, 'entities' | 'attributes'>,
+): { term: string; shares: (number | null)[] }[] {
+ return p.attributes.map((a) => ({
+ term: a.term,
+ shares: p.entities.map((e) =>
+ shareOf(a.values.find((v) => v.entity === e.entity)?.answers ?? 0, e.mentions),
+ ),
+ }));
+}
+
+/** A competitor leads an attribute by at least this many points for it to be a gap. */
+export const GAP_POINTS = 20;
+
+export interface PerceptionGap {
+ term: string;
+ competitor: string;
+ competitorShare: number;
+ brandShare: number;
+ /** The brand's place among the entities on this attribute; null when AI never uses it for the brand. */
+ brandRank: number | null;
+}
+
+/**
+ * The biggest gap (spec §9): the attribute where a competitor is most
+ * strongly associated and the brand least, by the widest margin, at least
+ * GAP_POINTS. Null when no competitor leads anything by that much.
+ */
+export function biggestGap(
+ p: Pick<MentionsPerception, 'entities' | 'attributes'>,
+): PerceptionGap | null {
+ const brandIndex = p.entities.findIndex((e) => e.isBrand);
+ if (brandIndex < 0) return null;
+ let best: PerceptionGap | null = null;
+ let bestMargin = GAP_POINTS;
+ for (const row of attributeShares(p)) {
+ const brandShare = row.shares[brandIndex] ?? 0;
+ for (let i = 0; i < row.shares.length; i++) {
+ const share = row.shares[i];
+ if (i === brandIndex || share === null || share - brandShare < bestMargin) continue;
+ bestMargin = share - brandShare;
+ const placed = row.shares.filter((s): s is number => s !== null && s > 0);
+ best = {
+ term: row.term,
+ competitor: p.entities[i].name,
+ competitorShare: share,
+ brandShare,
+ brandRank: brandShare > 0 ? placed.filter((s) => s > brandShare).length + 1 : null,
+ };
+ }
+ }
+ return best;
+}
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index 7aa83822a..57a88b64a 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -2826,6 +2826,54 @@ export type Database = {
},
]
}
+ mentions_answer_terms: {
+ Row: {
+ brand_id: string
+ created_at: string
+ entity: string
+ platform: string
+ prompt_id: string
+ region: string | null
+ result_id: string
+ terms: string[]
+ }
+ Insert: {
+ brand_id: string
+ created_at: string
+ entity: string
+ platform: string
+ prompt_id: string
+ region?: string | null
+ result_id: string
+ terms?: string[]
+ }
+ Update: {
+ brand_id?: string
+ created_at?: string
+ entity?: string
+ platform?: string
+ prompt_id?: string
+ region?: string | null
+ result_id?: string
+ terms?: string[]
+ }
+ Relationships: [
+ {
+ foreignKeyName: "mentions_answer_terms_brand_id_fkey"
+ columns: ["brand_id"]
+ isOneToOne: false
+ referencedRelation: "brands"
+ referencedColumns: ["id"]
+ },
+ {
+ foreignKeyName: "mentions_answer_terms_result_id_fkey"
+ columns: ["result_id"]
+ isOneToOne: false
+ referencedRelation: "prompt_results"
+ referencedColumns: ["id"]
+ },
+ ]
+ }
sentiment_overrides: {
Row: {
brand_id: string
@@ -4021,6 +4069,18 @@ export type Database = {
}
Returns: Json
}
+ mentions_perception: {
+ Args: {
+ p_brand_id: string
+ p_date_from: string
+ p_date_to?: string
+ p_platform?: string
+ p_region?: string
+ p_search?: string
+ p_topic_id?: string
+ }
+ Returns: Json
+ }
override_mention_sentiment: {
Args: { p_note?: string; p_result_id: string; p_sentiment: string }
Returns: Json