Skip to main content

🔍 Integració d'Elasticsearch i Catàlegs Externs a StarRocks

Aquest document detalla la configuració del motor de cerca de text complet i la seva federació amb el clúster OLAP per permetre cerques híbrides i semàntiques a DiscoveryPlus.

1. Desplegament d'Elasticsearch (Podman)​

Elasticsearch s'executa com un node únic (es01) en un contenidor Podman directament al host ymir.uab.cat.

  • Imatge: docker.elastic.co/elasticsearch/elasticsearch:8.17.3
  • Recursos: Assignació de 32GB de RAM (flag -m 32GB), optimitzat per indexar els grans volums de text de PATSTAT sense necessitat de clúster.
  • Xarxa: El port intern 9200 està mapejat al port 8008 de l'host.
  • IP Interna (Bridge): 10.89.1.2 (Xarxa: elastic).

2. Flux d'Ingesta de Dades (Logstash)​

La càrrega dels resums de patents es realitza mitjançant Logstash. El procés llegeix els fitxers CSV originals de l'EPO i els injecta a Elasticsearch.

Configuració del Pipeline (carga-abstracts2025b.conf):

  • Input: Fitxers CSV a /dades/downloads/patstat25b/tls203*.csv.
  • Filtre (CSV): Mapatge de les columnes appln_id, appln_abstract_lg i appln_abstract.
  • Output: Enviament de dades al host http://ymir.uab.cat:8008 cap a l'índex abstracts25bb.

3. Definició dels Catàlegs Externs a StarRocks​

L'arquitectura utilitza els "External Catalogs" de StarRocks per consultar Elasticsearch mitjançant SQL estàndard. Això permet que el sistema "vegi" els índexs de text com a taules federades.

Creació del Catàleg d'Abstracts (create-catalog-elastic.sh)​

CREATE EXTERNAL CATALOG elastic_abstracts
COMMENT 'elastic abstracts of patstat'
PROPERTIES (
    "type" = "es",
    "hosts" = "http://ymir.uab.cat:8008",
    "es.net.ssl" = "false",
    "user" = "elastic",
    "password" = ""
);

Actualment, el sistema està segmentat en tres catàlegs especialitzats:

  1. elastic_abstracts: Per a cerques sobre el resum de la patent (Índex: abstracts25bb).
  2. elastic_titles: Per a cerques ràpides sobre el títol de la patent.
  3. elastic_persons: Per a cerques de noms d'inventors o empreses (Cerca fuzzy).

4. Orquestració del Backend: FastAPI + SQLAlchemy​

A DiscoveryPlus, tota la lògica de cerca es centralitza a través de StarRocks, simplificant enormement el codi del backend:

  1. FastAPI: Rep els paràmetres de cerca de l'investigador (paraules clau, filtres booleans o entrada de LLM).
  2. SQLAlchemy: El backend de Python utilitza SQLAlchemy per generar consultes SQL que fan un JOIN entre les taules natives de StarRocks (metadades) i els catàlegs externs (elastic_abstracts).
  3. Execució Federada: StarRocks s'encarrega de demanar els resultats per rellevància a Elasticsearch i els retorna al backend ja creuats amb tota la informació relacional de PATSTAT en un sol JSON.

🛠️ Manteniment i Cicles d'Actualització (PATSTAT)​

Aquest document descriu les tasques recurrents i els procediments per a l'actualització semestral de les dades de patents a l'entorn ymir.uab.cat.

1. Estratègia d'Immutabilitat del Codi (Elasticsearch Aliases)​

Per evitar haver de modificar el codi SQL o la configuració dels catàlegs a StarRocks cada sis mesos, s'utilitza una capa d'abstracció mitjançant Àlies.

  • Lògica: El codi SQLAlchemy sempre apunta a un identificador genèric (ex: abstracts_alias).

  • Rotació: Quan es genera un nou índex (ex: abstracts2026a), es desassigna l'àlies de l'índex antic i s'assigna al nou en una sola operació atòmica.

Comanda de rotació (Exemple):

curl -X POST "localhost:8008/_aliases" -H 'Content-Type: application/json' -d'
{
  "actions": [
    { "remove": { "index": "abstracts2025b", "alias": "abstracts" } },
    { "add":    { "index": "abstracts2026a", "alias": "abstracts" } }
  ]
}'

2. Calendari d'Actualització Semestral​

  • Descàrrega: Baixada dels CSV a /dades/downloads/patstat<any><versió>/.

  • Indexació: Execució del pipeline de Logstash cap a un índex nou (ex: abstracts2026a).

  • Verificació: Comprovar que el recompte de documents és correcte.

  • Swap d'Àlies: Executar la rotació de l'àlies per fer les dades visibles a DiscoveryPlus instantàniament.

  • Ingesta StarRocks: Actualització de les taules OLAP (PATSTAT i KRAKEN via CDC).

3. Sanejament i Salut del Clúster​

Per evitar problemes d'ocupació de disc i garantir el rendiment:

A. Monitorització de l'Espai (qcow2) Abans de cada gran càrrega, comprovar l'estat dels nodes:

SHOW BACKENDS;

Si un node supera el 80% d'ocupació (UsedPct), cal ampliar el disc virtual o netejar fitxers orfes.

B. Gestió del "Trash" i Compactació StarRocks neteja segments vells cada 24h per defecte. En períodes d'actualització massiva, podem forçar la purga:

ADMIN SET FRONTEND CONFIG ("trash_file_expire_time_sec" = "3600");

4. Monitorització de l'Aplicació (FastAPI + SQLAlchemy)​

Latència de Consulta: Si les cerques triguen, verificar l'estat de les Materialized Views.

Logs d'Error: Vigilar els logs del contenidor Elasticsearch (podman logs es01) per detectar si la JVM de 32GB necessita un ajust del Heap Size.

Document: ELASTICSEARCH_INTEGRATION.md

Projecte: ymir.uab.cat

Data de revisió: Març 2026