Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion docs/datasources.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,70 @@ são instanciados no `lifespan` (startup) a partir de env vars e injetados no
`uniqueContentCount`, `uniqueContentWeight`, `lift`) ficam nulos e
`entityGraphStats` é `null`.

!!! warning "`entityCoverage` e a migração 035 do data-platform"
O dedup de republicações do `entityCoverage` (`uniqueContentCount`) usa a
coluna `news.content_key`, criada pela migração 035 do data-platform. A
ordem certa é aplicar a 035 **antes** de colocar esta versão no ar, mas a
API não quebra se a ordem for outra: o `PostgresDatasource` sonda a coluna
no catálogo (no máximo a cada 5 minutos por instância) e, sem ela, usa a
chave por hash exato, `COALESCE(n.content_hash, ne.unique_id)`. A 035
aplicada com o serviço no ar entra em uso em até 5 minutos, sem novo
deploy. Se a coluna sumir com a sonda ainda positiva (rollback da 035), o
erro `42703` (`column n.content_key does not exist`) é pego e a query é
refeita pela chave por hash. Com a 035 aplicada mas antes do backfill da
chave, o resultado é o mesmo de antes (cai no `content_hash`).

## Chave de conteúdo (dedup de republicações)

Um mesmo conteúdo publicado por vários órgãos (republicação) deve contar uma
vez nas contagens de "conteúdo único". A chave fica numa constante só,
`_CONTENT_DEDUP_KEY_SQL` em `datasources/postgres.py`:

```sql
COALESCE(n.content_key, n.content_hash, ne.unique_id)
```

- **`news.content_key`** (migração 035 do data-platform): agrupa
quase-duplicatas. É o `unique_id` do artigo-líder do grupo (o mais antigo),
calculado em lote pela tarefa `compute_content_keys` da DAG do grafo, que
roda a cada 6 horas e recalcula os últimos 10 dias a cada execução.
- **`content_hash`**: hash exato do conteúdo, para linhas ainda sem chave
(antes do backfill ou recém-ingeridas, até a próxima execução da DAG).
Sozinho quase não pega republicações entre órgãos, porque cada órgão
reescreve as URLs de imagem e de link.
- **`unique_id`**: garante uma chave não nula.

!!! important "Contrato com o data-platform: mesmo hash, mesma chave"
Depois do backfill quase toda linha tem `content_key`, e o `content_hash`
deixa de ser consultado. Para o `uniqueContentCount` nunca ficar **maior**
que o do dedup por hash exato, cada grupo de `content_hash` precisa caber
inteiro num grupo de `content_key`. Quem garante isso é o
`compute_content_keys` (DP-1b): ele une primeiro por `content_hash`,
herdando a chave do líder do hash sem janela de tempo nem guardas (inclusive
de artigos fora da janela de recálculo de 10 dias), e só depois aplica a
regra de quase-duplicata (H5). Sem esse passo, pares com o mesmo hash fora
das regras do H5 (conteúdo com menos de 30 palavras, Δt maior que 7 dias,
título na lista de exclusão) virariam líderes distintos e contariam duas
vezes. Em 21/10 havia 407 grupos de `content_hash` repetido (829 artigos);
129 deles se estendem por mais de 7 dias.

Resta uma janela transitória: um artigo recém-ingerido ainda sem chave cai
no `content_hash`, e o seu gêmeo de hash, já com chave, fica com o
`unique_id` do líder. Os dois contam à parte até a próxima execução da DAG
(até 6 horas).

Os espaços de chave não colidem (`unique_id` do líder contra hash de 16 hex).
A DAG do grafo do data-platform usa a mesma definição
(`ARTICLE_CONTENT_KEY_SQL`) para `entity_stats.unique_content_count` e
`entity_edges.unique_content_count`: mude as duas pontas juntas.

A mesma chave sai na API como **`Article.contentKey`**, calculada em Python
(`_content_dedup_key`, mesma precedência) a partir do `n.*` lido do Postgres,
por isso não exige a coluna. Só os caminhos servidos pelo Postgres a preenchem
(hoje, `entityArticles`); nas listas e na busca servidas pelo Typesense o campo
é `null`, porque o índice ainda não tem a chave (o `dedup: true` do Typesense
continua agrupando por `content_hash`, ver abaixo).

## Injeção por request

`get_context(request)` lê os datasources de `request.app.state` (populados pelo
Expand Down Expand Up @@ -69,7 +133,9 @@ capacidades, todas em cima da coleção `articles`:
- **Dedup / `group_by content_hash`.** Quando o resolver pede `dedup` (em
`articles`/`search` via `ArticleFilter.dedup` ou o arg `dedup` da `search`), a
query usa `group_by=content_hash` + `group_limit=1`, colapsando variações do
mesmo conteúdo (republicações entre órgãos) numa única linha.
mesmo conteúdo numa única linha. É o hash exato: republicações entre órgãos
com URLs reescritas não se juntam. Trocar o `group_by` pela chave de conteúdo
(`content_key`) exige indexá-la no Typesense antes (pendente).
- **Busca híbrida com `alpha` passthrough.** O arg `alpha` da `search` é repassado
ao `vector_query` (`embedding:([], alpha: <alpha>)`), controlando o peso do
vetor no ranking híbrido (default `0.3`; `0` = keyword puro, `1` = vetor puro).
Expand Down
27 changes: 23 additions & 4 deletions docs/exemplos.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ forma mais rápida de explorar a API.
!!! note "`filter.themes` faz OR entre níveis"
Os codes em `themes` casam contra L1 **ou** L2 **ou** L3 — não só o nível
topo. Use `themeLabel` (label de L1) para filtrar por rótulo legível, e
`dedup: true` para agrupar variações do mesmo conteúdo por `content_hash`.
`dedup: true` para agrupar variações do mesmo conteúdo por `content_hash`
(hash exato; ainda não usa a chave de quase-duplicata `contentKey`).

=== "Busca"

Expand Down Expand Up @@ -139,9 +140,27 @@ forma mais rápida de explorar a API.
!!! note "Contagens de artigos × de conteúdo"
`articleCount`/`weight` contam artigos; uma nota republicada por N
órgãos conta N vezes. `uniqueContentCount`/`uniqueContentWeight` contam
conteúdos distintos (`content_hash`). No `entityCoverage`, cada
conteúdo é creditado só ao primeiro órgão que o publicou no intervalo,
então `uniqueContentCount` pode ser somado entre órgãos e períodos.
conteúdos distintos pela chave de conteúdo (`news.content_key`, que
agrupa quase-duplicatas; sem ela, `content_hash`). No `entityCoverage`,
cada conteúdo é creditado só ao primeiro órgão que o publicou no
intervalo, então `uniqueContentCount` pode ser somado entre órgãos e
períodos.

```graphql
query ArtigosDaEntidade($id: String!) {
# Postgres: contentKey preenchido; artigos com a mesma chave são
# republicações do mesmo conteúdo ("também publicado por …")
entityArticles(entityId: $id, limit: 20) {
found
articles { uniqueId agency publishedAt contentKey }
}
}
```

!!! note "`contentKey` só nos caminhos do Postgres"
`Article.contentKey` vem preenchido no `entityArticles`. Em
`articles`/`search`/`article` (Typesense) ele é `null`, porque o índice
ainda não tem a chave.

## Queries e mutations autenticadas

Expand Down
17 changes: 11 additions & 6 deletions docs/reference/schema.graphql
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,11 @@ type Article {
mostSpecificThemeCode: String
mostSpecificThemeLabel: String

"""
Chave de conteúdo para agrupar republicações: artigos com a mesma chave são o mesmo conteúdo publicado por órgãos diferentes (quase-duplicatas). É a chave do entityCoverage.uniqueContentCount: news.content_key (uniqueId do artigo-líder do grupo); sem ela, o hash exato do conteúdo; sem ele, o próprio uniqueId. Preenchida só nos caminhos servidos pelo Postgres (entityArticles); null nas listas e na busca servidas pelo Typesense, que ainda não indexa a chave.
"""
contentKey: String

"""Hora de publicação (0-23), derivada de publishedAt"""
publicationHour: Int

Expand Down Expand Up @@ -327,7 +332,7 @@ type EntityCoveragePoint {
avgSentimentScore: Float

"""
Conteúdos distintos (content_hash) creditados a esta agência: cada conteúdo conta só para a primeira agência que o publicou no intervalo consultado, então o campo soma entre agências e períodos sem contar republicações. articleCount conta artigos.
Conteúdos distintos creditados a esta agência: cada conteúdo conta só para a primeira agência que o publicou no intervalo consultado, então o campo soma entre agências e períodos sem contar republicações. Republicações quase-duplicatas (mesma chave de conteúdo: news.content_key; sem ela, o hash exato do conteúdo; ver Article.contentKey) são o mesmo conteúdo. articleCount conta artigos.
"""
uniqueContentCount: Int!
}
Expand Down Expand Up @@ -369,7 +374,7 @@ type EntityNetworkEdge {
kind: String!

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
Co-menções com conteúdo distinto: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int
}
Expand All @@ -386,7 +391,7 @@ type EntityNetworkNode {
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam a entidade: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}
Expand All @@ -407,7 +412,7 @@ type EntityNode {
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam a entidade: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}
Expand Down Expand Up @@ -868,12 +873,12 @@ type RelatedEntity {
articleCount: Int

"""
Conteúdos distintos que mencionam o vizinho: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam o vizinho: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
Co-menções com conteúdo distinto: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int

Expand Down
17 changes: 11 additions & 6 deletions docs/reference/schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,11 @@ type Article {
mostSpecificThemeCode: String
mostSpecificThemeLabel: String

"""
Chave de conteúdo para agrupar republicações: artigos com a mesma chave são o mesmo conteúdo publicado por órgãos diferentes (quase-duplicatas). É a chave do entityCoverage.uniqueContentCount: news.content_key (uniqueId do artigo-líder do grupo); sem ela, o hash exato do conteúdo; sem ele, o próprio uniqueId. Preenchida só nos caminhos servidos pelo Postgres (entityArticles); null nas listas e na busca servidas pelo Typesense, que ainda não indexa a chave.
"""
contentKey: String

"""Hora de publicação (0-23), derivada de publishedAt"""
publicationHour: Int

Expand Down Expand Up @@ -338,7 +343,7 @@ type EntityCoveragePoint {
avgSentimentScore: Float

"""
Conteúdos distintos (content_hash) creditados a esta agência: cada conteúdo conta só para a primeira agência que o publicou no intervalo consultado, então o campo soma entre agências e períodos sem contar republicações. articleCount conta artigos.
Conteúdos distintos creditados a esta agência: cada conteúdo conta só para a primeira agência que o publicou no intervalo consultado, então o campo soma entre agências e períodos sem contar republicações. Republicações quase-duplicatas (mesma chave de conteúdo: news.content_key; sem ela, o hash exato do conteúdo; ver Article.contentKey) são o mesmo conteúdo. articleCount conta artigos.
"""
uniqueContentCount: Int!
}
Expand Down Expand Up @@ -380,7 +385,7 @@ type EntityNetworkEdge {
kind: String!

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
Co-menções com conteúdo distinto: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int
}
Expand All @@ -397,7 +402,7 @@ type EntityNetworkNode {
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam a entidade: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}
Expand All @@ -418,7 +423,7 @@ type EntityNode {
articleCount: Int

"""
Conteúdos distintos que mencionam a entidade: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam a entidade: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int
}
Expand Down Expand Up @@ -879,12 +884,12 @@ type RelatedEntity {
articleCount: Int

"""
Conteúdos distintos que mencionam o vizinho: republicações (mesmo content_hash) contam uma vez (entity_stats). Null sem estatística calculada.
Conteúdos distintos que mencionam o vizinho: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez (entity_stats). Null sem estatística calculada.
"""
uniqueContentCount: Int

"""
Co-menções com conteúdo distinto: republicações (mesmo content_hash) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
Co-menções com conteúdo distinto: republicações (mesma chave de conteúdo, ver Article.contentKey) contam uma vez. `weight` conta artigos. Null antes do cálculo do grafo.
"""
uniqueContentWeight: Int

Expand Down
Loading
Loading