Appearance

Glossaire ​

Termes spécifiques à better-search. Pour les concepts métier (Travel, Occurrence, Booking, etc.), voir le glossaire de spektrum-buchard-horizon.

Recherche & pertinence ​

  • Embedding — vecteur de 3584 nombres flottants qui représente le sens d'un texte. Calculé par BGE Multilingual Gemma2 via Infomaniak. Stocké en colonne embedding vector(3584) (extension pgvector).
  • Similarité cosinus — score entre 0 et 1 (typiquement) qui mesure à quel point deux embeddings « pointent dans la même direction » sémantiquement. 1.0 = sens identique, 0.0 = sans rapport. Exposée en réponse sous le nom semantic_score.
  • tsvector — type Postgres pour la recherche plein-texte. Construit ici via to_tsvector('french', …) avec pondération A/B/C sur name/subtitle/description. Voir colonne générée search_vector dans architecture/schema.md.
  • ts_rank_cd — fonction Postgres qui score la pertinence FTS d'un document par rapport à une tsquery. Plus c'est haut, mieux c'est. Exposé en réponse sous le nom tsvector_score.
  • websearch_to_tsquery — fonction Postgres qui parse une requête utilisateur (avec OR, -, guillemets, etc.) en tsquery exploitable. Utilisé pour transformer le ?search= du front en quelque chose que Postgres peut matcher.
  • RRF (Reciprocal Rank Fusion) — méthode de fusion de classements. Combine le rang vectoriel et le rang textuel en un score unique : w · 1/(60+rv) + (1-w) · 1/(60+rt). Voir architecture/hybrid-search.md et l'ADR 0002.
  • _relevance_score — score RRF final exposé dans chaque record retourné. Vaut 1.0 en branche filtre-seul (pas de ?search=). Ne pas l'exposer comme un pourcentage de pertinence en UI — c'est un score relatif.
  • semanticFloor / DEFAULT_SEMANTIC_FLOOR — plancher de similarité cosinus. Un voyage avec semantic_score < semanticFloor est éliminé sauf s'il passe via le plancher texte.
  • tsvectorFloor / DEFAULT_TSVECTOR_FLOOR — plancher de ts_rank_cd. Idem, plancher OR avec le précédent.
  • rrfVectorWeight / DEFAULT_RRF_VECTOR_WEIGHT — pondération w du RRF. 0 = pur texte, 1 = pur vecteur, 0.5 = équilibré.
  • Branche hybride — chemin SQL pris quand ?search= est non vide : CTE vector_search + text_search + rrf_scores avec planchers.
  • Branche filtre-seul — chemin SQL pris quand ?search= est vide : pas d'embedding, pas de RRF, simple SELECT … FROM travels_view WHERE … ORDER BY {orderBy}.

Modèle de données ​

  • raw_data — colonne JSONB qui contient le record voyage entier tel que retourné par l'amont Horizon. Source de vérité unique du service.
  • Colonne générée (GENERATED ALWAYS AS … STORED) — colonne Postgres calculée à partir d'autres colonnes (typiquement raw_data) et matérialisée sur disque. Indexable comme une colonne normale. Voir ADR 0001 et architecture/schema.md.
  • travels — table de stockage principale.
  • travels_view — vue Postgres qui ajoute next_departure calculé et filtre les voyages sans départ futur. Tous les SELECT de recherche passent par cette vue, pas la table.
  • next_departure — MIN() des departure_dates > CURRENT_DATE. Calculé dans la vue, exposé via nextDeparture en réponse (mode card).
  • jsonb_to_text_array(j, path) / jsonb_to_timestamp_array(j, path) — fonctions helper SQL utilisées dans les définitions de colonnes générées. IMMUTABLE, ne pas modifier sans plan de migration.

Ingestion / Reindex ​

  • Slow-backend — l'amont Horizon (SLOW_SEARCH_URL), historiquement nommé ainsi pour le distinguer de better-search. Documenté dans le knowledge base spektrum-buchard-horizon.
  • Reindex — cycle d'ingestion complet : pull amont, embed, UPSERT, purge stale, MAJ métriques. Voir architecture/reindex-lifecycle.md.
  • /seaside — sous-endpoint de l'amont (${SLOW_SEARCH_URL}/seaside) qui retourne les voyages balnéaires. Ingéré en deuxième position dans le pipeline, avec isSeaside=true injecté dans chaque record avant insertion.
  • is_seaside — colonne générée booléenne reflétant raw_data->>'isSeaside'. Indexée pour filtrer via ?seaside=true|false.
  • new_ids — set Python qui accumule les ids ingérés pendant un cycle. Le DELETE final supprime de travels tout id absent de ce set.
  • Lock global — threading.Lock + flag booléen _reindex_running qui empêche deux reindex de tourner en parallèle dans le même process. Voir ADR 0005.
  • _maybe_reindex() — méthode appelée par BuchardDatabase.__init__ au boot. Reindexe si la DB est vide ou si la dernière mise à jour date de > 15 min.

API & contrat front ​

  • infoDensity — paramètre query ?infoDensity=min|card|search|full qui contrôle quels champs sont renvoyés dans chaque record. Implémentation : apply_info_density dans src/_utils.py.
    • min : id, name, slug, scores.
    • card : id, name, scores, description, rating, slug, nextDeparture.
    • search : champs équivalents aux colonnes générées (destination, discount_club, is_valid, travel_ranges, departure_dates) + scores.
    • full (défaut si non précisé) : raw_data entier + scores.
  • ResultPage — modèle Pydantic de réponse de /travels. Champs : totalRecords, totalFilteredRecords, page, records.
  • totalRecords vs totalFilteredRecords — totalRecords = _total_count calculé par COUNT(*) OVER() (compte total après filtres + planchers, avant pagination). totalFilteredRecords = len(records) (taille de la page courante après pagination). Nommage hérité du contrat Horizon.

Observabilité ​

  • n_results_in_search — histogramme Prometheus du nombre de résultats retournés. Buckets [0, 10, 25, 50, 75, 100, 150, 200].
  • reindex_time_s — histogramme du temps d'un cycle reindex. Buckets [15, 30, 45, 60, 75, 90, 120, 240].
  • last_reindex_time — gauge timestamp Unix de la fin du dernier reindex.
  • db_size — gauge du COUNT(*) post-reindex.
  • prometheus-fastapi-instrumentator — bibliothèque qui ajoute automatiquement les métriques HTTP standard (http_requests_total, http_request_duration_seconds, etc.) sur /metrics.

Build & release ​

  • buchsearch — nom de l'image Docker (registry registry.internal.spektrum-suisse.ch/buchsearch). À ne pas confondre avec le nom du repo buchard-better-search.
  • VERSION_TAG — version applicative, injectée au docker build via --build-arg et exposée par l'endpoint /. Forme X.Y.Z ou X.Y.Z-staging.N.
  • BUILD_DATE — timestamp ISO 8601 du build Docker, idem, exposé sur /.
  • @spektrum/release-util — outil npm interne qui automatise la création de branches release/*, l'incrément SemVer, le changelog et le push de tags Git. Voir modules/releasing.md.
  • latest / latest-staging — tags Docker mobiles. latest pointe sur la dernière release prod, latest-staging sur la dernière release staging.
  • Yoyo --batch — flag passé à yoyo apply qui supprime la confirmation interactive. Indispensable pour un démarrage de conteneur non interactif.

Tests ​

  • date_offset — décalage de timedelta calculé dynamiquement (tests/conftest.py) pour que les dates de test_db.json (référence 2025-12-29) tombent toujours dans le futur au moment du run. Évite que les tests deviennent obsolètes avec le temps.
  • auto_reindex=False — argument à passer à BuchardDatabase dans les tests pour éviter le reindex automatique au boot.
  • mock_infomaniak_api / mock_slow_search_api — fixtures pytest qui patchent requests.post et requests.get pour retourner des embeddings et records fixtures (tests/test_embeddings.json, tests/test_query_embeddings.json, tests/test_db.json).
  • shifted_date — fixture qui décale une date YYYY-MM-DD d'origine par date_offset pour matcher la fixture.

Contributors

No contributors

Changelog

No recent changes