From a5d96f1e8f253ff557d566d49aa2dbddf78af335 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:19:02 -0300 Subject: [PATCH 01/10] test: dedup do entityCoverage por news.content_key com fallback para content_hash (red) --- .../datasources/test_postgres_entity_graph.py | 25 +++++++++++++------ tests/resolvers/test_entities.py | 11 ++++++++ 2 files changed, 28 insertions(+), 8 deletions(-) diff --git a/tests/datasources/test_postgres_entity_graph.py b/tests/datasources/test_postgres_entity_graph.py index 9bdd07d..c468ee0 100644 --- a/tests/datasources/test_postgres_entity_graph.py +++ b/tests/datasources/test_postgres_entity_graph.py @@ -571,26 +571,35 @@ def test_sql_period_em_utc_com_formato_inalterado(self): class TestEntityCoverageConteudoUnico: - """uniqueContentCount: cada conteúdo (COALESCE(content_hash, unique_id)) é - creditado só à PRIMEIRA agência que o publicou no intervalo — o campo soma - entre agências e períodos sem contar republicações duas vezes.""" + """uniqueContentCount: cada conteúdo (COALESCE(content_key, content_hash, + unique_id)) é creditado só à PRIMEIRA agência que o publicou no intervalo — + o campo soma entre agências e períodos sem contar republicações duas vezes.""" def test_sql_credita_a_primeira_publicacao(self): sql = _flat(_ENTITY_COVERAGE_SQL) - assert "PARTITION BY COALESCE(n.content_hash, ne.unique_id)" in sql + assert "PARTITION BY COALESCE(n.content_key, n.content_hash, ne.unique_id)" in sql assert "ORDER BY n.published_at, ne.unique_id" in sql # Uma linha por artigo (PK de news_entities + joins 1:1): COUNT(*) é exato. assert "COUNT(*) FILTER (WHERE m.is_first) AS unique_content_count" in sql def test_chave_de_dedup_isolada_numa_constante(self): - # A chave exata por content_hash quase não pega republicações entre - # órgãos (raramente idênticas byte a byte); trocar por uma chave de - # quase-duplicata deve mexer só nesta constante, sem mudar a API. - assert _CONTENT_DEDUP_KEY_SQL == "COALESCE(n.content_hash, ne.unique_id)" + # A chave de quase-duplicata (news.content_key, migração 035 do + # data-platform) mora só nesta constante; a API (`uniqueContentCount`) + # não muda. Mesma definição do `ARTICLE_CONTENT_KEY_SQL` do data-platform. + assert _CONTENT_DEDUP_KEY_SQL == "COALESCE(n.content_key, n.content_hash, ne.unique_id)" sql = _flat(_ENTITY_COVERAGE_SQL) assert f"PARTITION BY {_CONTENT_DEDUP_KEY_SQL}" in sql + assert sql.count("content_key") == 1 assert sql.count("content_hash") == 1 + def test_chave_de_quase_duplicata_tem_precedencia(self): + # content_key (grupo de quase-duplicatas) primeiro; o hash exato só vale + # para linhas ainda sem chave (antes do backfill ou fora da janela do + # cálculo); o unique_id garante chave não nula. Os espaços não colidem: + # content_key é o unique_id do líder do grupo, content_hash tem 16 hex. + args = _CONTENT_DEDUP_KEY_SQL.removeprefix("COALESCE(").removesuffix(")").split(", ") + assert args == ["n.content_key", "n.content_hash", "ne.unique_id"] + def test_sql_preserva_agregados_existentes(self): sql = _flat(_ENTITY_COVERAGE_SQL) assert "COUNT(*) AS article_count" in sql diff --git a/tests/resolvers/test_entities.py b/tests/resolvers/test_entities.py index 85b71a4..a014025 100644 --- a/tests/resolvers/test_entities.py +++ b/tests/resolvers/test_entities.py @@ -154,3 +154,14 @@ def test_unique_content_count_no_sdl(self): sdl = test_schema.as_str() block = sdl.split("type EntityCoveragePoint {", 1)[1].split("}", 1)[0] assert "uniqueContentCount: Int!" in block + + def test_unique_content_count_documenta_chave_de_quase_duplicata(self): + # A chave deixou de ser só o hash exato: a descrição precisa dizer que + # quase-duplicatas (news.content_key) contam como o mesmo conteúdo. + field = next( + f + for f in test_schema.get_type_by_name("EntityCoveragePoint").fields + if f.python_name == "unique_content_count" + ) + assert "content_key" in field.description + assert "quase-duplicatas" in field.description From 9298f694925aa200c8a75dc8ebb1ab8d7aa9261d Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:19:40 -0300 Subject: [PATCH 02/10] fix: dedup do entityCoverage por news.content_key com fallback para content_hash (green) --- docs/reference/schema.graphql | 2 +- docs/reference/schema.md | 2 +- src/graphql_api/datasources/postgres.py | 21 ++++++++++++++------- src/graphql_api/schema/types/entities.py | 8 +++++--- 4 files changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/reference/schema.graphql b/docs/reference/schema.graphql index b8f27c4..c0fa076 100644 --- a/docs/reference/schema.graphql +++ b/docs/reference/schema.graphql @@ -327,7 +327,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 news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. articleCount conta artigos. """ uniqueContentCount: Int! } diff --git a/docs/reference/schema.md b/docs/reference/schema.md index d3ae440..50d9daf 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -338,7 +338,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 news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. articleCount conta artigos. """ uniqueContentCount: Int! } diff --git a/src/graphql_api/datasources/postgres.py b/src/graphql_api/datasources/postgres.py index db4f9ab..71a1457 100644 --- a/src/graphql_api/datasources/postgres.py +++ b/src/graphql_api/datasources/postgres.py @@ -601,13 +601,20 @@ class TypesenseDocRecord(NewsRecord): """ # Chave de "mesmo conteúdo" para o dedup de republicações no entityCoverage -# (`n` = news, `ne` = news_entities). Hoje é o hash exato do conteúdo, que quase -# não pega republicações entre órgãos (raramente idênticas byte a byte); uma -# chave de quase-duplicata está em avaliação. Trocar a expressão aqui não muda a -# API (`uniqueContentCount`), mas `entity_stats.unique_content_count` e -# `entity_edges.unique_content_count` vêm da DAG do grafo no data-platform com a -# mesma definição — mantenha as duas pontas alinhadas. -_CONTENT_DEDUP_KEY_SQL = "COALESCE(n.content_hash, ne.unique_id)" +# (`n` = news, `ne` = news_entities). `news.content_key` (migração 035 do +# data-platform) agrupa quase-duplicatas: é o `unique_id` do artigo-líder do +# grupo, calculado em lote pela tarefa `compute_content_keys` da DAG do grafo. +# O hash exato (`content_hash`) só vale para linhas ainda sem chave (antes do +# backfill ou recém-ingeridas); ele quase não pega republicações entre órgãos, +# porque cada órgão reescreve as URLs de imagem e de link. Os espaços de chave +# não colidem (unique_id do líder contra hash de 16 hex). +# EXIGE a coluna `news.content_key`: sem a migração 035 aplicada, o +# entityCoverage falha com "column n.content_key does not exist". +# Trocar a expressão aqui não muda a API (`uniqueContentCount`), mas +# `entity_stats.unique_content_count` e `entity_edges.unique_content_count` vêm +# da DAG do grafo no data-platform (`ARTICLE_CONTENT_KEY_SQL`) com a mesma +# definição — mantenha as duas pontas alinhadas. +_CONTENT_DEDUP_KEY_SQL = "COALESCE(n.content_key, n.content_hash, ne.unique_id)" # Série temporal de cobertura de uma entidade por agência e período. # `$1` = granularidade (day/week/month), `$2` = entity_id, `$3` = date_from diff --git a/src/graphql_api/schema/types/entities.py b/src/graphql_api/schema/types/entities.py index c90a926..6b35a19 100644 --- a/src/graphql_api/schema/types/entities.py +++ b/src/graphql_api/schema/types/entities.py @@ -29,9 +29,11 @@ class EntityCoveragePoint: unique_content_count: int = strawberry.field( default=0, description=( - "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 " + "news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. articleCount " + "conta artigos." ), ) From 5d5a30c41f96e4b8bd3d12070f4cbf9a3f3f826b Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:20:33 -0300 Subject: [PATCH 03/10] test: Article.contentKey no entityArticles (Postgres) com a chave efetiva do dedup (red) --- tests/datasources/test_postgres.py | 47 ++++++++++++++++++++++++++ tests/resolvers/test_entities.py | 36 ++++++++++++++++++++ tests/test_article_publication_hour.py | 5 +++ 3 files changed, 88 insertions(+) diff --git a/tests/datasources/test_postgres.py b/tests/datasources/test_postgres.py index 3561541..e383f67 100644 --- a/tests/datasources/test_postgres.py +++ b/tests/datasources/test_postgres.py @@ -150,3 +150,50 @@ async def test_get_news_for_typesense_includes_embeddings_and_features(self): assert result.readability_flesch == 45.2 assert result.features == features conn.fetchrow.assert_awaited_once() + + +class TestNewsRecordContentKey: + """`NewsRecord.content_key` é a chave de conteúdo efetiva, com a mesma + precedência de `_CONTENT_DEDUP_KEY_SQL`: news.content_key (quase-duplicatas), + senão content_hash, senão o próprio unique_id. As leituras usam `n.*`, então + antes da migração 035 a coluna nem vem na linha e a chave cai no hash.""" + + @pytest.mark.asyncio + async def test_usa_content_key_quando_presente(self): + row = _sample_row(content_key="news-000", content_hash="abcdef0123456789") + pool, _ = _make_mock_pool(fetchrow_result=row) + result = await PostgresDatasource(pool).get_news_by_id("news-001") + assert result.content_key == "news-000" + + @pytest.mark.asyncio + async def test_cai_no_content_hash_sem_content_key(self): + row = _sample_row(content_key=None, content_hash="abcdef0123456789") + pool, _ = _make_mock_pool(fetchrow_result=row) + result = await PostgresDatasource(pool).get_news_by_id("news-001") + assert result.content_key == "abcdef0123456789" + + @pytest.mark.asyncio + async def test_cai_no_unique_id_sem_chave_nem_hash(self): + row = _sample_row(content_key=None, content_hash=None) + pool, _ = _make_mock_pool(fetchrow_result=row) + result = await PostgresDatasource(pool).get_news_by_id("news-001") + assert result.content_key == "news-001" + + @pytest.mark.asyncio + async def test_linha_sem_a_coluna_content_key_antes_da_035(self): + row = _sample_row(content_hash="abcdef0123456789") + assert "content_key" not in row + pool, _ = _make_mock_pool(fetchrow_result=row) + result = await PostgresDatasource(pool).get_news_by_id("news-001") + assert result.content_key == "abcdef0123456789" + + @pytest.mark.asyncio + async def test_entity_articles_propaga_a_chave(self): + rows = [ + _sample_row(unique_id="b", content_key="a", total_count=2), + _sample_row(unique_id="a", content_key="a", total_count=2), + ] + pool, _ = _make_mock_pool(fetch_result=rows) + records, total = await PostgresDatasource(pool).get_entity_articles("Q1", 10, 0) + assert total == 2 + assert [r.content_key for r in records] == ["a", "a"] diff --git a/tests/resolvers/test_entities.py b/tests/resolvers/test_entities.py index a014025..f5e4c63 100644 --- a/tests/resolvers/test_entities.py +++ b/tests/resolvers/test_entities.py @@ -1,9 +1,11 @@ +import re from unittest.mock import AsyncMock import pytest import strawberry from graphql_api.context import GraphQLContext +from graphql_api.datasources.postgres import NewsRecord from graphql_api.schema.resolvers.entities import EntityQuery from graphql_api.schema.resolvers.health import HealthQuery @@ -165,3 +167,37 @@ def test_unique_content_count_documenta_chave_de_quase_duplicata(self): ) assert "content_key" in field.description assert "quase-duplicatas" in field.description + + +class TestEntityArticlesContentKey: + """`Article.contentKey` no entityArticles (Postgres): a mesma chave do + uniqueContentCount, para o cliente agrupar republicações.""" + + @pytest.mark.asyncio + async def test_entity_articles_expoe_content_key(self): + mock_pg = AsyncMock() + mock_pg.get_entity_articles = AsyncMock( + return_value=( + [ + NewsRecord(unique_id="b", title="B", url="https://b", agency_key="ebc", content_key="a"), + NewsRecord(unique_id="a", title="A", url="https://a", agency_key="mec", content_key="a"), + NewsRecord(unique_id="c", title="C", url="https://c", agency_key="mec", content_key="c"), + ], + 3, + ) + ) + query = '{ entityArticles(entityId: "Q1") { found articles { uniqueId agency contentKey } } }' + result = await test_schema.execute(query, context_value=_make_ctx(postgres_ds=mock_pg)) + assert result.errors is None + arts = result.data["entityArticles"]["articles"] + assert [(a["uniqueId"], a["contentKey"]) for a in arts] == [("b", "a"), ("a", "a"), ("c", "c")] + + def test_content_key_no_sdl_nulavel_e_documentado(self): + art = test_schema.get_type_by_name("Article") + field = next(f for f in art.fields if f.python_name == "content_key") + # Nulável: null nos caminhos do Typesense. + assert re.search(r"^\s*contentKey: String$", test_schema.as_str(), re.M) + # Só os caminhos servidos pelo Postgres preenchem; o Typesense ainda não + # indexa a chave. + assert "entityArticles" in field.description + assert "Typesense" in field.description diff --git a/tests/test_article_publication_hour.py b/tests/test_article_publication_hour.py index 285c3c8..8c5c31d 100644 --- a/tests/test_article_publication_hour.py +++ b/tests/test_article_publication_hour.py @@ -36,3 +36,8 @@ def test_publication_hour_exposto_no_schema(): from graphql_api.schema import schema assert "publicationHour" in schema.as_str() + + +def test_content_key_ausente_por_padrao(): + # Caminhos do Typesense não têm a chave: o campo fica null. + assert _article(None).content_key is None From c763f2780dabdb6f3200e88d4fb3b014f52cc40a Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:21:01 -0300 Subject: [PATCH 04/10] feature: Article.contentKey no entityArticles (Postgres) com a chave efetiva do dedup (green) --- docs/reference/schema.graphql | 5 +++++ docs/reference/schema.md | 5 +++++ src/graphql_api/datasources/postgres.py | 17 +++++++++++++++++ src/graphql_api/schema/resolvers/entities.py | 1 + src/graphql_api/schema/types/article.py | 11 +++++++++++ 5 files changed, 39 insertions(+) diff --git a/docs/reference/schema.graphql b/docs/reference/schema.graphql index c0fa076..011ef48 100644 --- a/docs/reference/schema.graphql +++ b/docs/reference/schema.graphql @@ -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 diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 50d9daf..83c6d34 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -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 diff --git a/src/graphql_api/datasources/postgres.py b/src/graphql_api/datasources/postgres.py index 71a1457..274a51c 100644 --- a/src/graphql_api/datasources/postgres.py +++ b/src/graphql_api/datasources/postgres.py @@ -35,6 +35,8 @@ class NewsRecord: most_specific_theme_code: Optional[str] = None most_specific_theme_label: Optional[str] = None features: Optional[dict[str, Any]] = None + # Chave de conteúdo EFETIVA (ver `_content_dedup_key`), não a coluna crua. + content_key: Optional[str] = None @dataclass @@ -616,6 +618,20 @@ class TypesenseDocRecord(NewsRecord): # definição — mantenha as duas pontas alinhadas. _CONTENT_DEDUP_KEY_SQL = "COALESCE(n.content_key, n.content_hash, ne.unique_id)" + +def _content_dedup_key(row: dict) -> str: + """A chave de `_CONTENT_DEDUP_KEY_SQL` calculada em Python, para linhas de + `news` lidas com `n.*` (expostas como `Article.contentKey`). + + Mesma precedência do COALESCE (só NULL cai para a próxima). Diferente do + SQL, não exige a coluna: antes da migração 035 o `n.*` não traz + `content_key` e a chave cai no `content_hash`.""" + for column in ("content_key", "content_hash"): + value = row.get(column) + if value is not None: + return value + return row["unique_id"] + # Série temporal de cobertura de uma entidade por agência e período. # `$1` = granularidade (day/week/month), `$2` = entity_id, `$3` = date_from # (NULL = sem limite inferior), `$4` = date_to (NULL = sem limite superior). @@ -804,6 +820,7 @@ def _row_to_news_record(row: dict) -> NewsRecord: most_specific_theme_code=row.get("most_specific_theme_code"), most_specific_theme_label=row.get("most_specific_theme_label"), features=row.get("features"), + content_key=_content_dedup_key(row), ) diff --git a/src/graphql_api/schema/resolvers/entities.py b/src/graphql_api/schema/resolvers/entities.py index 5544b76..c4ae923 100644 --- a/src/graphql_api/schema/resolvers/entities.py +++ b/src/graphql_api/schema/resolvers/entities.py @@ -45,6 +45,7 @@ def _news_record_to_article(record) -> Article: theme_1_level_3_label=record.theme_l3_label, most_specific_theme_code=record.most_specific_theme_code, most_specific_theme_label=record.most_specific_theme_label, + content_key=record.content_key, ) diff --git a/src/graphql_api/schema/types/article.py b/src/graphql_api/schema/types/article.py index 61fb5ca..37eb75d 100644 --- a/src/graphql_api/schema/types/article.py +++ b/src/graphql_api/schema/types/article.py @@ -38,6 +38,17 @@ class Article: theme_1_level_3_label: Optional[str] = None most_specific_theme_code: Optional[str] = None most_specific_theme_label: Optional[str] = None + content_key: Optional[str] = strawberry.field( + default=None, + description=( + "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." + ), + ) @strawberry.field(description="Hora de publicação (0-23), derivada de publishedAt") def publication_hour(self) -> Optional[int]: From 7c72d6f1a82d5cceb4f6245646399c986cda6113 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:21:22 -0300 Subject: [PATCH 05/10] =?UTF-8?q?test:=20descri=C3=A7=C3=B5es=20das=20cont?= =?UTF-8?q?agens=20de=20conte=C3=BAdo=20=C3=BAnico=20citam=20a=20chave=20d?= =?UTF-8?q?e=20conte=C3=BAdo=20(red)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tests/test_schema.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tests/test_schema.py b/tests/test_schema.py index 01b876f..da1c269 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -199,3 +199,14 @@ def test_schema_md_embrulha_o_sdl_commitado(): assert committed_md == _load_export_script().render_markdown(committed_sdl), ( "docs/reference/schema.md não corresponde a schema.graphql. Rode `make docs-schema`." ) + + +def test_contagens_de_conteudo_unico_nao_prometem_hash_exato(): + # Depois do DP-1b/GQL-1b, entity_stats/entity_edges e o entityCoverage contam + # conteúdo pela chave de quase-duplicata (news.content_key), não só pelo + # hash exato: as descrições não podem prometer "mesmo content_hash". + from graphql_api.schema import schema + + sdl = schema.as_str() + assert "mesmo content_hash" not in sdl + assert sdl.count("mesma chave de conteúdo") >= 5 From 72ee624d3921d281538ad2f994d50e20f31d7696 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:21:58 -0300 Subject: [PATCH 06/10] =?UTF-8?q?docs:=20descri=C3=A7=C3=B5es=20das=20cont?= =?UTF-8?q?agens=20de=20conte=C3=BAdo=20=C3=BAnico=20citam=20a=20chave=20d?= =?UTF-8?q?e=20conte=C3=BAdo=20(green)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/schema.graphql | 12 +++++------ docs/reference/schema.md | 12 +++++------ .../schema/resolvers/public_content.py | 20 +++++++++---------- src/graphql_api/schema/types/entities.py | 6 +++--- 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/reference/schema.graphql b/docs/reference/schema.graphql index 011ef48..6b1eaf6 100644 --- a/docs/reference/schema.graphql +++ b/docs/reference/schema.graphql @@ -332,7 +332,7 @@ type EntityCoveragePoint { avgSentimentScore: Float """ - 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 news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. 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! } @@ -374,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 } @@ -391,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 } @@ -412,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 } @@ -873,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 diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 83c6d34..433d6fa 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -343,7 +343,7 @@ type EntityCoveragePoint { avgSentimentScore: Float """ - 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 news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. 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! } @@ -385,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 } @@ -402,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 } @@ -423,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 } @@ -884,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 diff --git a/src/graphql_api/schema/resolvers/public_content.py b/src/graphql_api/schema/resolvers/public_content.py index f199c4b..83936cf 100644 --- a/src/graphql_api/schema/resolvers/public_content.py +++ b/src/graphql_api/schema/resolvers/public_content.py @@ -90,8 +90,8 @@ class EntityNode: unique_content_count: Optional[int] = strawberry.field( default=None, description=( - "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." ), ) @@ -131,15 +131,15 @@ class RelatedEntity: unique_content_count: Optional[int] = strawberry.field( default=None, description=( - "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." ), ) unique_content_weight: Optional[int] = strawberry.field( default=None, description=( - "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." ), ) lift: Optional[float] = strawberry.field( @@ -179,8 +179,8 @@ class EntityNetworkNode: unique_content_count: Optional[int] = strawberry.field( default=None, description=( - "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." ), ) @@ -196,8 +196,8 @@ class EntityNetworkEdge: unique_content_weight: Optional[int] = strawberry.field( default=None, description=( - "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." ), ) diff --git a/src/graphql_api/schema/types/entities.py b/src/graphql_api/schema/types/entities.py index 6b35a19..afa09af 100644 --- a/src/graphql_api/schema/types/entities.py +++ b/src/graphql_api/schema/types/entities.py @@ -31,9 +31,9 @@ class EntityCoveragePoint: description=( "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 " - "news.content_key; sem ela, o mesmo content_hash) são o mesmo conteúdo. articleCount " - "conta artigos." + "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." ), ) From c1c4b8b40ff3b912a88e274cef821fd4970c46f6 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:22:24 -0300 Subject: [PATCH 07/10] =?UTF-8?q?docs:=20chave=20de=20conte=C3=BAdo=20(con?= =?UTF-8?q?tent=5Fkey)=20no=20dedup=20do=20entityCoverage,=20Article.conte?= =?UTF-8?q?ntKey=20e=20depend=C3=AAncia=20da=20migra=C3=A7=C3=A3o=20035?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/datasources.md | 42 +++++++++++++++++++++++++++++++++++++++++- docs/exemplos.md | 27 +++++++++++++++++++++++---- 2 files changed, 64 insertions(+), 5 deletions(-) diff --git a/docs/datasources.md b/docs/datasources.md index 9e4bb53..8d343ad 100644 --- a/docs/datasources.md +++ b/docs/datasources.md @@ -27,6 +27,44 @@ são instanciados no `lifespan` (startup) a partir de env vars e injetados no `uniqueContentCount`, `uniqueContentWeight`, `lift`) ficam nulos e `entityGraphStats` é `null`. +!!! warning "`entityCoverage` depende da 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: sem + ela a query falha com `column n.content_key does not exist`. Aplique a 035 + **antes** de colocar esta versão no ar. 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 + 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). 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. + +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 @@ -69,7 +107,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: )`), controlando o peso do vetor no ranking híbrido (default `0.3`; `0` = keyword puro, `1` = vetor puro). diff --git a/docs/exemplos.md b/docs/exemplos.md index b02c008..ab4a4f3 100644 --- a/docs/exemplos.md +++ b/docs/exemplos.md @@ -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" @@ -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 From ad4b0db535fb098233878615740eca0a2b185258 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:36:24 -0300 Subject: [PATCH 08/10] =?UTF-8?q?test:=20entityCoverage=20n=C3=A3o=20quebr?= =?UTF-8?q?a=20sem=20a=20coluna=20news.content=5Fkey=20(antes=20da=20035?= =?UTF-8?q?=20ou=20ap=C3=B3s=20rollback)=20(red)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...st_postgres_entity_coverage_content_key.py | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 tests/datasources/test_postgres_entity_coverage_content_key.py diff --git a/tests/datasources/test_postgres_entity_coverage_content_key.py b/tests/datasources/test_postgres_entity_coverage_content_key.py new file mode 100644 index 0000000..381aaea --- /dev/null +++ b/tests/datasources/test_postgres_entity_coverage_content_key.py @@ -0,0 +1,197 @@ +"""entityCoverage sem depender da ordem de deploy da migração 035 (GQL-1b). + +`_ENTITY_COVERAGE_SQL` lê `n.content_key` sempre que calcula a janela do dedup, +mesmo quando o cliente não pede `uniqueContentCount`. Sem a coluna, a query +inteira falharia, e com ela os tools `get_entity_profile` e +`get_policy_lifecycle` do gobus. O datasource sonda a coluna (cache com TTL) e +cai na chave por hash exato enquanto ela não existe. Se a coluna sumir com o +cache dizendo que existe (rollback da 035), o erro 42703 é pego, a query é +refeita com a chave por hash e o cache passa a dizer que não existe. +""" + +from unittest.mock import AsyncMock, MagicMock + +import asyncpg +import pytest + +from graphql_api.datasources.postgres import ( + _CONTENT_DEDUP_KEY_SQL, + _CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY, + _CONTENT_KEY_PROBE_TTL_S, + _ENTITY_COVERAGE_SQL, + _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY, + _NEWS_HAS_CONTENT_KEY_SQL, + PostgresDatasource, +) + +ROW = { + "period": "2026-10-01 00:00:00+00", + "agency_key": "mec", + "agency_name": "Ministério da Educação", + "article_count": 2, + "unique_content_count": 1, + "total_mentions": 3, + "avg_sentiment_score": None, +} + + +def _flat(sql: str) -> str: + return " ".join(sql.split()) + + +class _Clock: + def __init__(self, now: float = 1000.0): + self.now = now + + def __call__(self) -> float: + return self.now + + +def _make_pool(*, has_column, fetch_side_effect=None): + """`has_column`: retorno da sonda (`conn.fetchval`), um valor ou lista em + sequência. `fetch_side_effect`: efeitos de `conn.fetch` em sequência + (padrão: sempre `[ROW]`).""" + pool = MagicMock() + conn = AsyncMock() + if isinstance(has_column, list): + conn.fetchval = AsyncMock(side_effect=has_column) + else: + conn.fetchval = AsyncMock(return_value=has_column) + if fetch_side_effect is None: + conn.fetch = AsyncMock(return_value=[ROW]) + else: + conn.fetch = AsyncMock(side_effect=fetch_side_effect) + acm = AsyncMock() + acm.__aenter__ = AsyncMock(return_value=conn) + acm.__aexit__ = AsyncMock(return_value=False) + pool.acquire.return_value = acm + return pool, conn + + +def _sqls(conn) -> list[str]: + return [c.args[0] for c in conn.fetch.await_args_list] + + +class TestSqlSemContentKey: + def test_chave_legada_e_o_hash_exato(self): + assert _CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY == "COALESCE(n.content_hash, ne.unique_id)" + + def test_sql_legado_so_troca_a_chave(self): + # Mesmo SQL, com a chave por hash no lugar da chave com content_key: + # nada além da chave pode divergir entre os dois caminhos. + assert _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY == _ENTITY_COVERAGE_SQL.replace( + _CONTENT_DEDUP_KEY_SQL, _CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY + ) + assert "content_key" not in _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY + assert "content_key" in _ENTITY_COVERAGE_SQL + + def test_sonda_procura_news_content_key_no_catalogo(self): + sql = _flat(_NEWS_HAS_CONTENT_KEY_SQL) + assert sql.startswith("SELECT EXISTS") + assert "pg_attribute" in sql + # Mesma resolução de `news` pelo search_path que as queries usam. + assert "attrelid = to_regclass('news')" in sql + assert "attname = 'content_key'" in sql + assert "NOT attisdropped" in sql + + def test_ttl_de_cinco_minutos(self): + assert _CONTENT_KEY_PROBE_TTL_S == 300 + + +class TestEntityCoverageEscolheAChave: + @pytest.mark.asyncio + async def test_com_a_coluna_usa_content_key(self): + pool, conn = _make_pool(has_column=True) + ds = PostgresDatasource(pool, clock=_Clock()) + + rows = await ds.entity_coverage("Q1", "day", "2026-10-01", "2026-10-08") + + assert rows == [ROW] + conn.fetchval.assert_awaited_once_with(_NEWS_HAS_CONTENT_KEY_SQL) + assert _sqls(conn) == [_ENTITY_COVERAGE_SQL] + + @pytest.mark.asyncio + async def test_sem_a_coluna_cai_no_hash_sem_erro(self): + # Merge do GQL-1b antes da 035: o entityCoverage não quebra. + pool, conn = _make_pool(has_column=False) + ds = PostgresDatasource(pool, clock=_Clock()) + + rows = await ds.entity_coverage("Q1", "day", "2026-10-01", "2026-10-08") + + assert rows == [ROW] + assert _sqls(conn) == [_ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY] + assert conn.fetch.await_args.args[1:3] == ("day", "Q1") + + @pytest.mark.asyncio + async def test_sonda_uma_vez_dentro_do_ttl(self): + clock = _Clock() + pool, conn = _make_pool(has_column=True) + ds = PostgresDatasource(pool, clock=clock) + + await ds.entity_coverage("Q1") + clock.now += _CONTENT_KEY_PROBE_TTL_S - 1 + await ds.entity_coverage("Q2") + + assert conn.fetchval.await_count == 1 + assert _sqls(conn) == [_ENTITY_COVERAGE_SQL, _ENTITY_COVERAGE_SQL] + + @pytest.mark.asyncio + async def test_coluna_criada_depois_entra_em_uso_apos_o_ttl(self): + # 035 aplicada com o serviço no ar: sem novo deploy, a chave nova + # passa a valer na primeira consulta depois do TTL. + clock = _Clock() + pool, conn = _make_pool(has_column=[False, True]) + ds = PostgresDatasource(pool, clock=clock) + + await ds.entity_coverage("Q1") + clock.now += _CONTENT_KEY_PROBE_TTL_S + await ds.entity_coverage("Q1") + + assert conn.fetchval.await_count == 2 + assert _sqls(conn) == [_ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY, _ENTITY_COVERAGE_SQL] + + +class TestEntityCoverageColunaRemovida: + @pytest.mark.asyncio + async def test_coluna_removida_com_cache_positivo_refaz_com_hash(self): + # Rollback da 035 (DROP COLUMN) com o GQL-1b no ar e o cache ainda + # dizendo que a coluna existe: refaz com a chave por hash, sem erro. + erro = asyncpg.exceptions.UndefinedColumnError("column n.content_key does not exist") + pool, conn = _make_pool(has_column=True, fetch_side_effect=[erro, [ROW], [ROW]]) + ds = PostgresDatasource(pool, clock=_Clock()) + + rows = await ds.entity_coverage("Q1", "day", "2026-10-01", "2026-10-08") + + assert rows == [ROW] + assert _sqls(conn) == [_ENTITY_COVERAGE_SQL, _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY] + assert conn.fetch.await_args_list[0].args[1:] == conn.fetch.await_args_list[1].args[1:] + + # O cache passa a dizer que a coluna não existe: a próxima consulta, + # dentro do TTL, vai direto pela chave por hash, sem sondar de novo. + await ds.entity_coverage("Q1") + assert conn.fetchval.await_count == 1 + assert _sqls(conn)[-1] == _ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY + + @pytest.mark.asyncio + async def test_outros_erros_propagam_sem_refazer(self): + erro = asyncpg.exceptions.QueryCanceledError("canceling statement due to statement timeout") + pool, conn = _make_pool(has_column=True, fetch_side_effect=[erro]) + ds = PostgresDatasource(pool, clock=_Clock()) + + with pytest.raises(asyncpg.exceptions.QueryCanceledError): + await ds.entity_coverage("Q1") + + assert conn.fetch.await_count == 1 + + @pytest.mark.asyncio + async def test_42703_no_sql_legado_propaga(self): + # Coluna ausente que não é a content_key: o SQL legado também falha, e + # o erro sobe em vez de entrar em laço. + erro = asyncpg.exceptions.UndefinedColumnError("column n.agency_key does not exist") + pool, conn = _make_pool(has_column=False, fetch_side_effect=[erro]) + ds = PostgresDatasource(pool, clock=_Clock()) + + with pytest.raises(asyncpg.exceptions.UndefinedColumnError): + await ds.entity_coverage("Q1") + + assert conn.fetch.await_count == 1 From c3b515b6cdca03228f2c2c146c885b139b288d1c Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:38:04 -0300 Subject: [PATCH 09/10] fix: entityCoverage sonda news.content_key e cai no content_hash sem a coluna (green) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Desacopla o deploy da ordem da migração 035: antes dela (ou depois de um rollback dela) o entityCoverage usa a chave por hash exato em vez de falhar, o que derrubaria também get_entity_profile e get_policy_lifecycle do gobus. A sonda vai ao catálogo no máximo a cada 5 min por instância; um 42703 com o cache positivo refaz a query pela chave por hash. Comentário de _CONTENT_DEDUP_KEY_SQL registra o contrato com o DP-1b: mesmo content_hash implica mesma content_key. --- src/graphql_api/datasources/postgres.py | 106 +++++++++++++++--- .../datasources/test_postgres_entity_graph.py | 3 + 2 files changed, 92 insertions(+), 17 deletions(-) diff --git a/src/graphql_api/datasources/postgres.py b/src/graphql_api/datasources/postgres.py index 274a51c..f59446a 100644 --- a/src/graphql_api/datasources/postgres.py +++ b/src/graphql_api/datasources/postgres.py @@ -2,6 +2,7 @@ import logging import math import os +import time from dataclasses import dataclass, field from datetime import date, datetime from typing import Any, Optional @@ -605,18 +606,49 @@ class TypesenseDocRecord(NewsRecord): # Chave de "mesmo conteúdo" para o dedup de republicações no entityCoverage # (`n` = news, `ne` = news_entities). `news.content_key` (migração 035 do # data-platform) agrupa quase-duplicatas: é o `unique_id` do artigo-líder do -# grupo, calculado em lote pela tarefa `compute_content_keys` da DAG do grafo. -# O hash exato (`content_hash`) só vale para linhas ainda sem chave (antes do -# backfill ou recém-ingeridas); ele quase não pega republicações entre órgãos, -# porque cada órgão reescreve as URLs de imagem e de link. Os espaços de chave -# não colidem (unique_id do líder contra hash de 16 hex). -# EXIGE a coluna `news.content_key`: sem a migração 035 aplicada, o -# entityCoverage falha com "column n.content_key does not exist". +# grupo, calculado em lote pela tarefa `compute_content_keys` da DAG do grafo +# (a cada 6h, recalculando os últimos 10 dias). O hash exato (`content_hash`) +# quase não pega republicações entre órgãos, porque cada órgão reescreve as URLs +# de imagem e de link. Os espaços de chave não colidem (unique_id do líder +# contra hash de 16 hex). +# CONTRATO com o DP-1b: cada grupo de `content_hash` cabe inteiro num grupo de +# `content_key` (mesmo hash ⇒ mesma chave). O `compute_content_keys` une primeiro por +# `content_hash`, herdando a chave do líder do hash sem janela de tempo nem +# guardas (conteúdo curto, título excluído) — inclusive de artigos fora da +# janela de recálculo de 10 dias —, e só depois aplica o H5. Depois do +# backfill quase toda linha tem chave e o hash deixa de ser consultado; sem esse +# contrato, pares com o mesmo hash fora das regras do H5 (Δt > 7 dias, conteúdo +# curto) virariam líderes distintos e o uniqueContentCount SUBIRIA em relação ao +# dedup por hash. O hash só vale para linhas ainda sem chave: antes do backfill +# ou recém-ingeridas até a próxima execução da DAG (até 6h; nesse intervalo, um +# artigo novo cujo gêmeo de hash já tem chave conta à parte). +# A coluna pode não existir (deploy antes da 035, ou rollback dela): o +# `entity_coverage` sonda a coluna (`_NEWS_HAS_CONTENT_KEY_SQL`, cache de +# `_CONTENT_KEY_PROBE_TTL_S`) e, sem ela, usa `_CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY`. # Trocar a expressão aqui não muda a API (`uniqueContentCount`), mas # `entity_stats.unique_content_count` e `entity_edges.unique_content_count` vêm # da DAG do grafo no data-platform (`ARTICLE_CONTENT_KEY_SQL`) com a mesma # definição — mantenha as duas pontas alinhadas. _CONTENT_DEDUP_KEY_SQL = "COALESCE(n.content_key, n.content_hash, ne.unique_id)" +# A chave enquanto `news.content_key` não existe: só o hash exato. +_CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY = "COALESCE(n.content_hash, ne.unique_id)" + +# Sonda da coluna `news.content_key` no catálogo. `to_regclass('news')` resolve +# a tabela pelo search_path, como as queries; devolve false (e não erro) se a +# coluna ou a tabela não existirem. +_NEWS_HAS_CONTENT_KEY_SQL = """ +SELECT EXISTS ( + SELECT 1 FROM pg_attribute + WHERE attrelid = to_regclass('news') + AND attname = 'content_key' + AND NOT attisdropped +) +""" +# Validade do resultado da sonda: a 035 aplicada com o serviço no ar entra em +# uso em até 5 minutos, sem novo deploy. +_CONTENT_KEY_PROBE_TTL_S = 300 +# SQLSTATE undefined_column (42703): coluna sumiu com o cache dizendo que existe. +_UNDEFINED_COLUMN_SQLSTATE = "42703" def _content_dedup_key(row: dict) -> str: @@ -647,7 +679,7 @@ def _content_dedup_key(row: dict) -> str: # com news/news_features, então COUNT(*) = COUNT(DISTINCT unique_id) — e, sem # DISTINCT, o agregado pode ser por hash (o sort após a janela era o gargalo). # Score de sentimento aninhado com fallback plano (ver `_AGENCY_ANALYTICS_SQL`). -_ENTITY_COVERAGE_SQL = f""" +_ENTITY_COVERAGE_SQL_TEMPLATE = """ WITH mentions AS ( SELECT to_char(DATE_TRUNC($1, ne.published_at AT TIME ZONE 'UTC'), 'YYYY-MM-DD HH24:MI:SS"+00"') AS period, @@ -656,7 +688,7 @@ def _content_dedup_key(row: dict) -> str: n.agency_name, COALESCE(nf.features->'sentiment'->>'score', nf.features->>'sentiment_score')::float AS sentiment_score, ROW_NUMBER() OVER ( - PARTITION BY {_CONTENT_DEDUP_KEY_SQL} + PARTITION BY {dedup_key} ORDER BY n.published_at, ne.unique_id ) = 1 AS is_first FROM news_entities ne @@ -678,6 +710,11 @@ def _content_dedup_key(row: dict) -> str: GROUP BY period, m.agency_key, m.agency_name ORDER BY period """ +_ENTITY_COVERAGE_SQL = _ENTITY_COVERAGE_SQL_TEMPLATE.format(dedup_key=_CONTENT_DEDUP_KEY_SQL) +# O mesmo SQL enquanto `news.content_key` não existe (ver `entity_coverage`). +_ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY = _ENTITY_COVERAGE_SQL_TEMPLATE.format( + dedup_key=_CONTENT_DEDUP_KEY_SQL_SEM_CONTENT_KEY +) # Busca de entidades por nome ou alias: UNION entre match exato por alias # normalizado (unaccent + lower) e match fuzzy por trigrama (pg_trgm %). @@ -1095,8 +1132,11 @@ def _row_to_typesense_doc(row: dict) -> TypesenseDocRecord: class PostgresDatasource: - def __init__(self, pool): + def __init__(self, pool, *, clock=time.monotonic): self._pool = pool + self._clock = clock + # Cache da sonda de `news.content_key`: (existe?, instante da sonda). + self._content_key_probe: tuple[bool, float] | None = None @classmethod async def from_env( @@ -1455,17 +1495,49 @@ async def entity_coverage( Retorna lista de dicts com chaves: `period`, `agency_key`, `agency_name`, `article_count`, `unique_content_count`, `total_mentions`, `avg_sentiment_score`. + + Sem a coluna `news.content_key` (antes da 035 ou depois de um rollback + dela), o dedup cai na chave por hash exato em vez de falhar. """ + params = ( + granularity, + entity_id, + date.fromisoformat(date_from) if date_from else None, + date.fromisoformat(date_to) if date_to else None, + ) async with self._pool.acquire() as conn: - rows = await conn.fetch( - _ENTITY_COVERAGE_SQL, - granularity, - entity_id, - date.fromisoformat(date_from) if date_from else None, - date.fromisoformat(date_to) if date_to else None, - ) + if not await self._news_has_content_key(conn): + rows = await conn.fetch(_ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY, *params) + return [dict(r) for r in rows] + try: + rows = await conn.fetch(_ENTITY_COVERAGE_SQL, *params) + except Exception as exc: + if getattr(exc, "sqlstate", None) != _UNDEFINED_COLUMN_SQLSTATE: + raise + # Coluna removida com o cache dizendo que existe (rollback da + # 035): refaz pela chave por hash e guarda que ela não existe. + logger.warning("entityCoverage: %s; refazendo com a chave por content_hash", exc) + self._content_key_probe = (False, self._clock()) + rows = await conn.fetch(_ENTITY_COVERAGE_SQL_SEM_CONTENT_KEY, *params) return [dict(r) for r in rows] + async def _news_has_content_key(self, conn) -> bool: + """Se `news.content_key` (migração 035 do data-platform) existe. + + Sonda o catálogo no máximo uma vez a cada `_CONTENT_KEY_PROBE_TTL_S` + por instância. Desacopla o deploy da API da ordem da migração: antes da + 035 o entityCoverage usa a chave por hash exato, e a coluna nova entra em + uso sozinha depois do TTL.""" + now = self._clock() + cached = self._content_key_probe + if cached is not None and now - cached[1] < _CONTENT_KEY_PROBE_TTL_S: + return cached[0] + exists = bool(await conn.fetchval(_NEWS_HAS_CONTENT_KEY_SQL)) + if cached is None or cached[0] != exists: + logger.info("news.content_key %s", "presente" if exists else "ausente") + self._content_key_probe = (exists, now) + return exists + async def entity_search( self, query: str, diff --git a/tests/datasources/test_postgres_entity_graph.py b/tests/datasources/test_postgres_entity_graph.py index c468ee0..524009f 100644 --- a/tests/datasources/test_postgres_entity_graph.py +++ b/tests/datasources/test_postgres_entity_graph.py @@ -44,6 +44,9 @@ def _make_mock_pool(fetch_results=None, *, fetchrow=None): else: conn.fetch = AsyncMock(side_effect=list(fetch_results)) conn.fetchrow = AsyncMock(return_value=fetchrow) + # Sonda de `news.content_key` do entityCoverage: coluna presente (035 + # aplicada). Sem ela, ver test_postgres_entity_coverage_content_key.py. + conn.fetchval = AsyncMock(return_value=True) acm = AsyncMock() acm.__aenter__ = AsyncMock(return_value=conn) From a2f055d92702ba3cce82d3b1ae3de28651a0c481 Mon Sep 17 00:00:00 2001 From: nitai Date: Wed, 21 Oct 2026 21:39:03 -0300 Subject: [PATCH 10/10] =?UTF-8?q?docs:=20entityCoverage=20sem=20a=20coluna?= =?UTF-8?q?=20content=5Fkey=20cai=20no=20hash;=20contrato=20mesmo=20hash?= =?UTF-8?q?=20=E2=87=92=20mesma=20chave=20com=20o=20DP-1b?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/datasources.md | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/datasources.md b/docs/datasources.md index 8d343ad..0dc1dea 100644 --- a/docs/datasources.md +++ b/docs/datasources.md @@ -27,12 +27,18 @@ são instanciados no `lifespan` (startup) a partir de env vars e injetados no `uniqueContentCount`, `uniqueContentWeight`, `lift`) ficam nulos e `entityGraphStats` é `null`. -!!! warning "`entityCoverage` depende da migração 035 do data-platform" +!!! 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: sem - ela a query falha com `column n.content_key does not exist`. Aplique a 035 - **antes** de colocar esta versão no ar. Com a 035 aplicada mas antes do - backfill da chave, o resultado é o mesmo de antes (cai no `content_hash`). + 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) @@ -47,12 +53,32 @@ 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 - recalcula os últimos 10 dias a cada execução. + 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). Sozinho quase não pega republicações - entre órgãos, porque cada órgão reescreve as URLs de imagem e de link. + (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