Skip to content

feature: rede ego-centrada, lift/articleCount, dateTo exclusivo no entityCoverage, url no ArticleSummary e Flesch pt-BR (GQL-1) - #32

Merged
nitaibezerra merged 20 commits into
mainfrom
feature/rede-ego-lift-url-flesch-ptbr
Oct 22, 2026
Merged

nitaibezerra merged 20 commits into
mainfrom
feature/rede-ego-lift-url-flesch-ptbr

Conversation

@nitaibezerra

@nitaibezerra nitaibezerra commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Note

Pré-condições de deploy cumpridas (22/10/2026). O deploy depende da migração 032 do data-platform (data-platform#209, DP-1): entity(id), relatedEntities e entityNetwork (inclusive no modo legado que o portal usa) fazem LEFT JOIN em entity_stats e leem entity_edges.unique_content_count; relatedEntities e entityGraphStats leem entity_graph_meta.

  • 032 aplicada em produção: migration_history id 52, run 39700227672.
  • DAG project_entity_graph executada depois da 032: entity_stats com 51.328 linhas; entity_graph_meta com total_articles = 202.705, total_unique_content = 202.444, computed_at = 2026-10-22 00:44 UTC.

O merge foi antecipado de 29/10 por decisão do responsável, com baseline das consultas legadas antes e depois do deploy.

Contexto

O roteiro de testes do Gobus (gobus-mcp) achou seis problemas cuja causa está na API:

Problema no Gobus Causa na API Mudança
Rede não centrada na entidade entityNetwork corta as arestas pelo peso global; as arestas fortes entre vizinhos expulsam as da própria entidade modo egoCentered
Entidades genéricas ("Brasil", "Governo Federal") dominando os relacionados ordenação só por co-menção bruta orderBy: LIFT + articleCount
Duplicatas (nota republicada por N órgãos conta N vezes) contagens por artigo, sem dedup por content_hash uniqueContentCount / uniqueContentWeight
Série truncada / dia a mais entityCoverage com <= dateTo e limites dependentes de fuso dias UTC, dateTo estritamente exclusivo
Artigos citados sem link ArticleSummary sem url url + agencyKey
Flesch com escala inglesa (notas negativas) só readability_flesch (fórmula inglesa) readabilityFleschPtbr (Martins et al., 1996)

Consumidor principal: gobus-mcp PR-B (gobus-mcp#13).

Mudanças na API

Todas aditivas no schema (args com default, campos novos nullable ou com default). Sem os args novos, cada query devolve o mesmo que antes. A única mudança de comportamento é o dateTo exclusivo do entityCoverage, descrito na próxima seção.

entityNetwork

  • Args novos: egoCentered: Boolean = false, maxNodes: Int = 30 (clamp 1–100), includeNeighborEdges: Boolean = true.
  • Modo ego: os nós são a entidade mais os maxNodes vizinhos mais fortes (weight ≥ 2, desempate por id), com a entidade em primeiro.
    • Entram todas as arestas da entidade para esses vizinhos.
    • Só as arestas entre vizinhos são cortadas em limit (clamp 1–500), e só aparecem com includeNeighborEdges.
    • depth é ignorado.
    • Os SQLs são _ENTITY_NETWORK_EGO_NODES_SQL e _ENTITY_NETWORK_EGO_EDGES_SQL, que compartilham o mesmo CTE neighbors. O datasource ainda tira nós e arestas órfãos e duplicados (par invertido), caso a DAG recalcule entity_edges entre as duas queries.
  • Modo legado (default): usa as mesmas CTEs recursivas, com os mesmos parâmetros. Só ganha LEFT JOIN entity_stats (pela PK, então não multiplica linhas) e a coluna e.unique_content_count.
  • Campos novos: EntityNetworkNode.articleCount e uniqueContentCount; EntityNetworkEdge.uniqueContentWeight. Todos nullable.

relatedEntities, entity(id) e entityGraphStats

  • relatedEntities:
    • Args novos: orderBy: RelatedEntityOrder = WEIGHT (WEIGHT | UNIQUE_CONTENT | LIFT) e minWeight: Int = 1. O default 1 é a lista de sempre; minWeight: 2 descarta co-menções únicas (o gobus passa explicitamente).
    • Campos novos, todos nullable: articleCount e uniqueContentCount (do vizinho), uniqueContentWeight (da aresta) e lift.
    • lift = weight · N / (cnt_entidade · cnt_vizinho), com N = entity_graph_meta.total_articles e cnt = entity_stats.article_count. Há um NULLIF em cada termo, então o lift fica NULL quando falta estatística de uma das pontas, quando falta a meta ou quando algum termo é 0.
    • Ordenação por CASE no parâmetro, que passa por whitelist no datasource, com NULLS LAST e desempate por weight DESC, other_id.
  • entity(id) ganha articleCount e uniqueContentCount.
  • Query nova: entityGraphStats { totalArticles totalUniqueContent computedAt }. Retorna null enquanto não houver linha em entity_graph_meta.

entityCoverage

  • Datas em dias UTC: dateFrom inclusivo, dateTo estritamente exclusivo:
    • published_at >= ($3::date)::timestamp AT TIME ZONE 'UTC'
    • published_at < ($4::date)::timestamp AT TIME ZONE 'UTC'
  • period continua com o mesmo texto ("2026-08-27 00:00:00+00"). Agora o truncamento é em UTC fixo e o texto sai por to_char, sem depender do TimeZone da sessão.
  • Campo novo uniqueContentCount: Int!:
    • Cada conteúdo (COALESCE(content_hash, unique_id)) é creditado só à primeira agência que o publicou dentro do intervalo, via ROW_NUMBER() … ORDER BY published_at, unique_id.
    • Com isso, o campo pode ser somado entre agências e períodos.
    • Não depende da 032: content_hash existe desde a migração 009.
    • A expressão da chave de dedup fica isolada em _CONTENT_DEDUP_KEY_SQL (postgres.py).
    • Limitação conhecida: o hash exato quase não muda as contagens na prática, porque republicações entre órgãos raramente são idênticas byte a byte. Há uma chave de quase-duplicata em avaliação.
    • Trocar a chave mexe só nessa constante, sem mudar a API. Mas entity_stats e entity_edges.unique_content_count vêm da DAG do data-platform com a mesma definição, então a troca precisa andar junto nas duas pontas.

ArticleSummary (trendingThemes.topArticles)

  • url: String (o include_fields do Typesense passa a pedir url) e agencyKey: String.
  • agencyName continua igual, por compatibilidade. Ele sempre carregou a key, e agora o SDL documenta isso.

Flesch pt-BR

  • Campos novos:
    • ArticleFeatures.readabilityFleschPtbr: Float, lido de features.readability_flesch_ptbr.
    • AgencyPeriodMetrics.avgReadabilityFleschPtbr: Float, que passa por _as_float por causa do Decimal no graphql-core 3.3.
    • AgencyPeriodMetrics.readabilityFleschPtbrCount: Int: quantos artigos do grupo já têm o índice (cobertura do backfill 033).
  • As duas variantes SQL do agencyAnalytics mudam: MONTH/WEEK e DAY, com contagem 0 nos dias que o generate_series preenche.
  • readabilityFlesch e avgReadabilityFlesch não mudam. Só ganharam uma descrição no SDL dizendo que usam a fórmula inglesa.

Mudanças de comportamento: consumidores e impacto

entityCoverage com dateTo exclusivo. Antes, o filtro <= $4::timestamptz com uma data já excluía o último dia na prática. Ele só incluía os artigos publicados exatamente às 00:00:00 do dateTo. Os limites também dependiam do fuso: o asyncpg converte o date para timestamptz pelo fuso do processo, que é UTC no Cloud Run, mas num make dev em BRT virava 03:00 UTC.

  • gobus-mcp:
    • já manda dateTo exclusivo (utc_day_bounds, coverage_range), então não há impacto;
    • o get_entity_profile repassa a data do usuário, que já era exclusiva na prática, então a única diferença é o artigo das 00:00:00.
  • portal: não usa entityCoverage, nem em origin/development nem em origin/main. O campo só aparece no snapshot src/lib/graphql/schema.graphql. Se um dia passar a usar, precisa mandar dateTo = último dia + 1.

relatedEntities sem args novos não muda. Os defaults são orderBy: WEIGHT e minWeight: 1. Com eles, a lista é idêntica à de antes, inclusive nos empates (conferido contra o SQL de origin/main), então os chips de /entidades/[slug] no portal não mudam. O limiar weight ≥ 2 só vale quando pedido: minWeight: 2 ou entityNetwork(egoCentered: true), que é opt-in.

Portal, em geral. O portal chama entity(id), relatedEntities(id, limit) e entityNetwork(id, depth, limit) sem os args novos. O schema é aditivo e o drift gate do portal (operações × SDL) não é afetado. O snapshot do portal pode ser atualizado depois. A ressalva é a dependência da 032 descrita no topo.

Dependência do data-platform (DP-1, migração 032)

  • A data-platform#209 cria:
    • entity_edges.unique_content_count;
    • entity_stats (PK entity_id; uma linha por entidade com menção);
    • entity_graph_meta (linha única id = 1).
  • Os nomes conferem com os usados aqui. entity_stats.entity_id é VARCHAR(64), como em entity_registry.
  • Definições usadas pelo lift e pelas contagens:
    • total_articles = artigos distintos com ≥ 1 menção canônica em news_entities;
    • total_unique_content = COUNT(DISTINCT COALESCE(news.content_hash, unique_id)) sobre esses artigos;
    • entity_edges.unique_content_count é NULL nas arestas estruturais e nas de co-menção até o primeiro run.
  • Entre a 032 e a primeira execução da DAG, as linhas de entity_stats e entity_graph_meta podem não existir. Os LEFT JOINs devolvem NULL, o lift não divide por zero e entityGraphStats vem null.
  • Todas as queries novas (ego e related) filtram kind = 'co_mention', como as antigas.
  • is_generic e generic_reason de entity_stats são curadoria (não calculados pela DAG) e não são expostos neste PR.

Checagem antes do merge (somente leitura):

SELECT to_regclass('entity_stats') IS NOT NULL AS stats,
       to_regclass('entity_graph_meta') IS NOT NULL AS meta,
       EXISTS (SELECT 1 FROM information_schema.columns
               WHERE table_name = 'entity_edges' AND column_name = 'unique_content_count') AS edges_col,
       (SELECT computed_at FROM entity_graph_meta WHERE id = 1) AS graph_run;

Rollback. O rollback da 032 dá DROP nas tabelas. Se for preciso reverter a 032, o deploy do GQL-1 tem que ser revertido antes.

Não coloquei fallback em runtime para tabela ausente. Isso exigiria duplicar cada SQL do grafo numa variante sem estatísticas. A ordem de deploy acima cobre o caso.

Critérios de aceitação

  1. entityNetwork legado devolve os mesmos nós e arestas.
    • Conferido num Postgres 15 local descartável, comparando o SQL de origin/main com o novo. Nós e arestas idênticos para 5 ids (hub, médios, sem estatística e inexistente) × depth 0–2 × limit 5/50/500.
    • A refazer em produção depois da 032, com 3 ids (um hub, um médio e um pequeno): rodar o SQL antigo e o novo e comparar (entity_id, …) / (src, dst, weight, kind). Nos empates de peso no corte do LIMIT, o legado já não era determinístico, e isso continua igual.
  2. p95 < 300 ms.
    • Medido num grafo sintético com 80k entidades, 2,35M arestas, hub com grau 38k, 300k notícias e 1,5M menções. Os números são indicativos:

      Query p50 p95
      entityNetwork ego, nós (30) 3 ms 15 ms
      entityNetwork ego, arestas (30 / 50) 7 ms 26 ms
      entityNetwork ego, arestas (100 / 500) 24 ms 36 ms
      relatedEntities WEIGHT (antes → depois) 13 → 15 ms 48 → 50 ms
      relatedEntities LIFT 19 ms 137 ms
      entityNetwork legado, arestas, hub (antes ≈ depois) ~390 ms ~1,9 s
      entityNetwork legado, nós, hub com 38k nós (antes → depois) 168 → 232 ms —
    • A linha das arestas do legado mostra um problema que já existia: ele faz IN sobre todos os vizinhos. O modo ego resolve isso.

    • Nos nós do legado, o JOIN de stats custa cerca de +40% num hub, mas é desprezível nas entidades comuns (< 1 ms).

    • entityCoverage, num hub com 68k menções, MONTH, sem datas: p50 de ~170 ms, igual ao anterior. Isso depois de juntar news_features antes da janela e trocar COUNT(DISTINCT) por COUNT(*), que é exato porque a PK garante uma linha por artigo.

    • Plano a rodar em produção depois da 032 e da DAG, com os ids de maior grau:

      SELECT id, count(*) FROM (SELECT src_id id FROM entity_edges WHERE kind = 'co_mention'
                                UNION ALL SELECT dst_id FROM entity_edges WHERE kind = 'co_mention') x
      GROUP BY id ORDER BY 2 DESC LIMIT 3;
      -- PREPARE com o texto de _ENTITY_NETWORK_EGO_EDGES_SQL / _RELATED_ENTITIES_SQL (postgres.py)
      PREPARE ego_edges(varchar, int, int, boolean, int) AS <_ENTITY_NETWORK_EGO_EDGES_SQL>;
      EXPLAIN (ANALYZE, BUFFERS) EXECUTE ego_edges('<id>', 30, 2, true, 50);
      PREPARE related(varchar, bigint, text, int) AS <_RELATED_ENTITIES_SQL>;
      EXPLAIN (ANALYZE, BUFFERS) EXECUTE related('<id>', 12, 'lift', 2);
  3. Sanidade do lift.
    • Localmente, os valores batem com weight·N/(cnt_a·cnt_b). O lift é NULL sem stats, sem meta e com N = 0. Os nulos vão para o fim, e sem lift a ordem cai no desempate por peso.
    • Em produção: relatedEntities(id: <hub>, orderBy: LIFT) deve tirar do topo "Brasil" e "Governo Federal", que aparecem em orderBy: WEIGHT. O lift do 1º colocado deve ser > 1. Um par conferido à mão com entity_stats e entity_graph_meta deve dar o mesmo valor.

Testes

  • Suíte completa: 643 passed. ruff check limpo.
  • SDL de referência regenerado (make docs-schema); o gate test_sdl_de_referencia_em_sincronia_com_o_codigo passa.
  • mkdocs build --strict ok.
  • TDD por feature (commits test: … (red) → feature: / fix: … (green)). Os testes cobrem:
    • clamps;
    • modo ego com todas as arestas do foco, sem órfãos e sem duplicados;
    • legado com os mesmos SQLs e parâmetros;
    • orderBy, minWeight e lift null-safe;
    • datas e period do entityCoverage, e uniqueContentCount;
    • url e agencyKey;
    • Flesch pt-BR;
    • SDL.
  • Fora da suíte: os SQLs foram executados num Postgres 15 local descartável, com fixture do schema e grafo sintético, para conferir os pontos de equivalência e desempenho acima.

🤖 Generated with Claude Code

…tas (red)

GQL-1. O roteiro de testes do Gobus mostrou que a rede legada (CTE
recursiva, arestas cortadas por peso global) não fica centrada na
entidade: com limit=50 as arestas mais pesadas entre vizinhos expulsam
as do próprio foco.

Cobre:
- modo legado (default, usado pelo portal) com as mesmas queries
  recursivas e os mesmos parâmetros posicionais; só ganha LEFT JOIN em
  entity_stats e e.unique_content_count;
- modo ego (egoCentered): foco + top maxNodes vizinhos por peso (>= 2),
  todas as arestas do foco preservadas, arestas entre vizinhos cortadas
  em limit; clamps de maxNodes (1–100) e limit (1–500); depth ignorado;
- sem nós ou arestas órfãos mesmo se o grafo mudar entre as queries;
- articleCount/uniqueContentCount nos nós e uniqueContentWeight nas
  arestas, nulos quando faltam estatísticas;
- assinatura do SDL com os args novos.
…nt/uniqueContentWeight (green)

GQL-1. Args novos (aditivos; o default mantém o modo legado do portal):

- egoCentered (false), maxNodes (30, clamp 1–100), includeNeighborEdges
  (true). No modo ego, os nós são a entidade + seus maxNodes vizinhos
  mais fortes (weight >= 2, desempate por id) e TODAS as arestas da
  entidade para eles entram; só as arestas entre vizinhos são cortadas
  em limit (clamp 1–500). depth é ignorado.
- _ENTITY_NETWORK_EGO_NODES_SQL/_EDGES_SQL compartilham o mesmo CTE
  neighbors (mesma ordem + LIMIT ⇒ mesmo conjunto); o datasource ainda
  poda nós e arestas órfãos caso a DAG recalcule entity_edges entre as
  duas queries. Foco primeiro na lista de nós; ids sempre parametrizados.
- Legado: mesmas queries recursivas e mesmos parâmetros; só ganha LEFT
  JOIN em entity_stats (PK, não multiplica linhas) e a coluna
  e.unique_content_count. Conferido num Postgres local descartável:
  nós/arestas idênticos aos do SQL anterior para 5 ids × depth 0–2 ×
  limit 5/50/500.
- EntityNetworkNode ganha articleCount/uniqueContentCount e
  EntityNetworkEdge ganha uniqueContentWeight, todos nullable.

Requer a migração 032 do data-platform (entity_stats e
entity_edges.unique_content_count) aplicada antes do deploy.
SDL de referência regenerado (make docs-schema).
… e entityGraphStats (red)

GQL-1. Entidades genéricas ("Brasil", "Governo Federal") dominam os
vizinhos por peso bruto; o lift (weight·N / (cnt_ego·cnt_vizinho))
destaca associações específicas, e uniqueContentWeight desconta
republicações.

Cobre:
- datasource: $3 = ordenação (weight|unique_content|lift, whitelist;
  inválida levanta sem consultar), $4 = peso mínimo (default 2, clamp
  >= 1), limit continua em $2; SQL com LEFT JOIN em entity_stats (das
  duas pontas) e entity_graph_meta, NULLIF nos termos do lift e ORDER BY
  com NULLS LAST e desempate weight desc, other_id;
- mapeamento de articleCount/uniqueContentCount/uniqueContentWeight/lift
  (Decimal → float) e nulos quando faltam estatísticas;
- entity(id) com articleCount/uniqueContentCount via LEFT JOIN;
- Query.entityGraphStats (entity_graph_meta), null sem linha ou sem
  Postgres;
- SDL: enum RelatedEntityOrder, args novos e campos nullable.
…id) e entityGraphStats (green)

GQL-1.

- relatedEntities ganha orderBy: RelatedEntityOrder = WEIGHT
  (WEIGHT | UNIQUE_CONTENT | LIFT) e minWeight: Int = 2, e os campos
  nullable articleCount, uniqueContentCount (do vizinho),
  uniqueContentWeight (da aresta) e lift.
- lift = weight·N / (cnt_ego·cnt_vizinho), N =
  entity_graph_meta.total_articles e cnt = entity_stats.article_count;
  NULLIF em cada termo ⇒ NULL quando falta estatística de uma ponta, a
  meta ou algum termo é 0. ORDER BY por CASE no parâmetro (whitelist no
  datasource), NULLS LAST, desempate weight desc, other_id.
- Com orderBy WEIGHT e minWeight 1 a lista é idêntica à do SQL anterior
  (conferido num Postgres local descartável, inclusive empates);
  minWeight 2 só remove as co-menções únicas.
- entity(id): articleCount/uniqueContentCount via LEFT JOIN em
  entity_stats (o batch de entitySuggestions não muda).
- Query.entityGraphStats { totalArticles totalUniqueContent computedAt },
  null sem linha em entity_graph_meta.

Mudança de default: relatedEntities passa a omitir vizinhos com
weight 1 (minWeight 2). minWeight: 1 restaura a lista anterior.

Requer a migração 032 do data-platform aplicada antes do deploy.
SDL de referência regenerado.
…ivo (red)

GQL-1. O filtro comparava `published_at <= $4::timestamptz` com uma data:
meia-noite do dateTo no fuso da sessão, ou seja, exclusivo na prática
exceto pelos artigos publicados exatamente às 00:00:00, e dependente do
TimeZone da conexão. O gobus-mcp já manda dateTo = último dia + 1.

Cobre: datas repassadas como date; limites
`>= ($3::date)::timestamp AT TIME ZONE 'UTC'` e
`< ($4::date)::timestamp AT TIME ZONE 'UTC'`; `period` com o mesmo
texto de antes ("AAAA-MM-DD 00:00:00+00") calculado em UTC fixo; e a
descrição do campo documentando a convenção.
…vo (green)

GQL-1.

- Limites `ne.published_at >= ($3::date)::timestamp AT TIME ZONE 'UTC'`
  e `< ($4::date)::timestamp AT TIME ZONE 'UTC'`: dateTo estritamente
  exclusivo. Antes, `<= $4::timestamptz` incluía os artigos publicados
  exatamente às 00:00:00 do dateTo e os limites dependiam do fuso: o
  asyncpg converte o `date` para timestamptz pelo fuso do PROCESSO
  (Cloud Run = UTC; num `make dev` em BRT os limites viravam 03:00 UTC).
- `period` truncado em UTC fixo e formatado com to_char no mesmo texto
  que o `timestamptz::text` de uma sessão UTC dava
  ("2026-08-27 00:00:00+00"), sem depender do TimeZone da sessão.
- Descrição do campo documenta a convenção (para incluir o dia D,
  dateTo = D + 1).

Conferido num Postgres local descartável com o processo em UTC (como
no Cloud Run): period, articleCount, totalMentions e avgSentimentScore
idênticos aos do SQL anterior para day/week/month; a única diferença é
o artigo das 00:00:00 do dateTo, que sai. O resultado novo é o mesmo
com sessão ou processo em America/Sao_Paulo.

Consumidores: o gobus-mcp já manda dateTo exclusivo (utc_day_bounds) e
o get_entity_profile repassa a data do usuário (já era exclusiva na
prática). O portal não usa entityCoverage.
…ira agência (red)

GQL-1. Uma mesma nota republicada por N agências conta N vezes em
articleCount (o roteiro do Gobus achou séries infladas por duplicatas).
uniqueContentCount credita cada conteúdo, COALESCE(content_hash,
unique_id), só à primeira agência que o publicou no intervalo (ROW_NUMBER
por published_at, unique_id), então o campo pode ser somado entre
agências e períodos.

Cobre o SQL (janela + COUNT DISTINCT FILTER, agregados existentes
preservados), o mapeamento no resolver e o campo não nulo no SDL.
…imeira agência (green)

GQL-1.

- CTE `mentions` com ROW_NUMBER() OVER (PARTITION BY
  COALESCE(n.content_hash, ne.unique_id) ORDER BY n.published_at,
  ne.unique_id) = 1 AS is_first; o agregado ganha
  COUNT(DISTINCT unique_id) FILTER (WHERE is_first) por (period,
  agência). A janela roda sobre as menções já filtradas pelo intervalo:
  o crédito vai para a primeira agência que publicou o conteúdo DENTRO
  do intervalo consultado, o que mantém o campo somável (a soma em
  qualquer granularidade = conteúdos distintos do intervalo).
- period passa a ser calculado no CTE (mesmo texto); article_count,
  total_mentions e avg_sentiment_score não mudam (mesmas linhas de
  news_entities × news × news_features).
- EntityCoveragePoint.uniqueContentCount: Int! (default 0).

Conferido num Postgres local descartável: republicações (mesmo
content_hash) em três agências creditadas só à primeira; soma por dia e
por mês igual ao nº de conteúdos distintos; demais colunas idênticas ao
SQL anterior. Não depende da migração 032 (content_hash existe desde a
009). SDL de referência regenerado.
GQL-1. O Gobus cita os artigos em alta sem link porque ArticleSummary
não tem url (o Typesense tem). E agencyName, apesar do nome, carrega a
key da agência (campo `agency` do Typesense).

Cobre: include_fields pede url; url e agencyKey mapeados (null quando
ausentes); agencyName mantido por compatibilidade, com descrição
apontando para agencyKey.
GQL-1. trendingThemes.topArticles passa a pedir `url` ao Typesense e
ArticleSummary ganha url e agencyKey (nullable, aditivos). agencyName
continua com o mesmo valor (a key, campo `agency` do Typesense), agora
documentado no SDL; consumidores novos devem usar agencyKey.

SDL de referência regenerado.
GQL-1. O readability_flesch gravado hoje usa a fórmula inglesa (escala
distorcida para português: notas negativas em agências normais). O
data-platform (DP-1) passa a gravar features.readability_flesch_ptbr
(Martins et al., 1996).

Cobre:
- ArticleFeatures.readabilityFleschPtbr (null quando ausente ou não
  numérico; bool/str rejeitados como nos demais escalares);
- agencyAnalytics MONTH/WEEK e DAY: AVG e COUNT de
  readability_flesch_ptbr, com contagem 0 nos dias preenchidos pelo
  generate_series; avg_readability_flesch inalterado;
- AgencyPeriodMetrics.avgReadabilityFleschPtbr (Decimal → float) e
  readabilityFleschPtbrCount;
- SDL.
GQL-1.

- ArticleFeatures.readabilityFleschPtbr: Float, lido de
  features.readability_flesch_ptbr (gravado pelo DP-1 do data-platform).
- agencyAnalytics (MONTH/WEEK e DAY): AVG e COUNT de
  readability_flesch_ptbr; no DAY, contagem 0 nos dias preenchidos.
  AgencyPeriodMetrics ganha avgReadabilityFleschPtbr (via _as_float, por
  causa do Decimal no graphql-core 3.3) e readabilityFleschPtbrCount,
  para o consumidor medir a cobertura do backfill.
- readabilityFlesch/avgReadabilityFlesch seguem iguais; só ganham
  descrição no SDL apontando que são a fórmula inglesa.

Conferido num Postgres local descartável (MONTH e DAY). Sem dependência
da migração 032: a chave nova do JSONB só fica nula até o backfill.
SDL de referência regenerado.
…dência da migração 032

- datasources.md: PostgresDatasource atende também entity,
  relatedEntities, entityNetwork e entityGraphStats; aviso de que essas
  queries dependem de entity_stats, entity_graph_meta e
  entity_edges.unique_content_count (migração 032 do data-platform) e
  do comportamento antes da primeira execução da DAG.
- exemplos.md: aba "Entidades" (lift, rede ego-centrada, cobertura com
  uniqueContentCount, entityGraphStats; query validada contra o schema)
  e gotchas de dateTo exclusivo, rede legada × egoCentered, minWeight
  padrão 2 e agencyName com a key.
…ty_edges (red)

entity_edges não tem CHECK (src_id < dst_id); a ordem canônica do par
de co-menção é só convenção da DAG. Se o par aparecer nos dois
sentidos, o modo ego devolveria o vizinho duas vezes e duas arestas
para o mesmo par. A rede deve manter um nó por entidade e uma aresta
por par (a de maior peso, que vem primeiro).
…(green)

_prune_ego_network mantém o primeiro nó de cada entity_id e a primeira
aresta de cada par {src, dst} (as arestas chegam por peso desc, então
fica a mais forte). Protege o modo ego de um par gravado nos dois
sentidos em entity_edges, já que src_id < dst_id é convenção da DAG e
não CHECK no banco. Invariantes do modo ego reconferidos no Postgres
local.
…tes da janela

Num grafo sintético (300k notícias, 1,5M menções; entidade-hub com 68k
menções, MONTH sem limite de datas), a versão com COUNT(DISTINCT) depois
do ROW_NUMBER levava p50 ~265 ms contra ~205 ms do SQL anterior: o
DISTINCT força GroupAggregate com sort (spill em disco com work_mem de
4 MB) num nó single-thread acima da janela.

- news_features entra no CTE (antes da janela, ainda paralelo) e o
  score de sentimento sai já calculado;
- COUNT(*) no lugar de COUNT(DISTINCT unique_id): news_entities tem PK
  (unique_id, entity_id) e os joins com news/news_features são 1:1, então
  há uma linha por artigo e as contagens são as mesmas.

Resultado idêntico (linhas ordenadas, AVG arredondado) para MONTH/WEEK/
DAY em três entidades, e de volta a ~p50 170 ms no caso do hub (DAY com
janela de 3 meses: +10 ms sobre o SQL anterior). Testes de SQL
atualizados para as novas expressões.
O dedup exato por content_hash quase não muda as contagens na prática:
republicações entre órgãos raramente são idênticas byte a byte, e uma
chave de quase-duplicata está em avaliação. A expressão da chave
(COALESCE(n.content_hash, ne.unique_id)) deve viver numa única
constante, para ser trocada sem mudar a API (uniqueContentCount fica
com o mesmo nome).
…(green)

A expressão COALESCE(n.content_hash, ne.unique_id) sai do SQL para uma
constante documentada, interpolada no PARTITION BY (constante de
código, não entrada do usuário). O SQL renderizado é idêntico ao
anterior. O comentário registra que o hash exato quase não pega
republicações entre órgãos e que entity_stats/entity_edges (DAG do
grafo no data-platform) usam a mesma definição, então uma troca de
chave precisa andar junto nas duas pontas.
…ortal (red)

O default 2 tirava os vizinhos de co-menção única e encolhia os chips de
/entidades/[slug] no portal, que chama relatedEntities(id, limit) sem
args novos. Com default 1 a lista padrão volta a ser idêntica à de
antes; o gobus passa minWeight: 2 explicitamente. O limiar >= 2 do modo
ego (opt-in) não muda.
…rtal (green)

Default de minWeight volta a incluir os vizinhos de co-menção única
(weight >= 1): sem args novos, relatedEntities devolve a mesma lista de
antes, então os chips do portal não encolhem. minWeight: 2 continua
disponível para cortar ruído (o gobus passa explicitamente). O limiar
>= 2 do entityNetwork egoCentered (opt-in) não muda. Descrição do
campo e gotcha em docs/exemplos.md atualizados; SDL regenerado.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant