Un job d’indexation peut terminer en vert alors que la recherche sert un catalogue incomplet. Le dernier lot a été accepté, mais certaines lignes du Bulk API ont échoué ; un événement de suppression s’est perdu ; une mise à jour plus ancienne a écrasé la plus récente. L’application répond vite et sans erreur technique, tout en affichant un produit indisponible ou en cachant une donnée qui existe dans le système métier.
Elasticsearch amplifie la qualité du modèle qu’on lui confie. Des identifiants instables créent des doublons, un mapping dynamique transforme un champ selon le premier document reçu et un refresh forcé après chaque écriture dégrade progressivement l’indexation. Le coût caché apparaît au support, qui doit expliquer pourquoi la fiche, la recherche et la base ne racontent pas la même histoire.
En pratique, l’index est une projection reconstruisible d’une source faisant foi. Chaque document possède une identité métier, une version de source et une transformation versionnée. Le pipeline sait reprendre un lot, traiter chaque résultat, mesurer son retard et reconstruire un nouvel index sans modifier celui qui sert encore les requêtes.
Contre-intuitivement, rendre une écriture immédiatement visible n’améliore pas toujours la fiabilité. Un refresh explicite augmente le coût et ne prouve ni que toutes les lignes du lot sont passées, ni que le résultat de recherche est juste. Une intégration API sur mesure doit séparer accusé d’indexation, visibilité pour la recherche, complétude métier et pertinence des résultats.
Faire d’Elasticsearch une projection, pas la vérité métier
La base, le PIM, l’ERP ou le service métier reste responsable des données transactionnelles. Elasticsearch optimise la recherche, le filtrage, les facettes ou l’agrégation. Une correction effectuée directement dans l’index disparaîtra au prochain rejeu et ne réparera pas la source. Le runbook interdit donc les modifications manuelles qui ne sont pas reproduites par le pipeline officiel.
Le contrat nomme les champs copiés, les champs calculés et les jointures réalisées au moment de la projection. Il précise la fraîcheur attendue et les cas où l’application peut consulter la source directement. Une fiche critique ne déduit pas la disponibilité d’un index ancien si une vérification métier plus récente est nécessaire avant l’achat.
Cas concret : le catalogue recherche un produit avec son prix et son stock. Le PIM possède le contenu, l’ERP possède le prix et l’OMS possède le disponible. Le document matérialise un état horodaté de ces trois sources ; il ne devient pas propriétaire du stock parce que sa réponse arrive en quelques millisecondes.
Construire des documents stables et rejouables
L’identifiant Elasticsearch vient d’une clé métier stable. Le même produit, client ou dossier réutilise le même _id à chaque indexation, quel que soit le job ou le nombre de retries. Un identifiant aléatoire transforme une mise à jour en nouveau document et rend les suppressions impossibles à rattacher de façon sûre.
Le document contient une version de source ou un horodatage métier comparable. Le worker refuse qu’un événement ancien écrase un état plus récent. Cette protection appartient au contrat de synchronisation, surtout lorsque plusieurs files, backfills et traitements temps réel écrivent vers le même alias.
La transformation est déterministe : une même entrée, avec la même version de mapping et les mêmes référentiels, produit le même document. Les enrichissements non déterministes sont datés ou sortis du pipeline. Un rejeu complet peut alors reconstruire l’index, expliquer une différence et vérifier qu’aucun document fantôme n’a été créé.
Maîtriser mappings, templates et analyseurs
Le mapping est un contrat de recherche. Il distingue texte analysé, mot-clé exact, nombre, date, géopoint et objet imbriqué selon les requêtes attendues. Les multi-fields permettent par exemple une recherche plein texte et un tri exact sans dupliquer la source. Le choix vient des cas d’usage, pas de la forme apparente d’un exemple JSON.
Le mapping dynamique accélère une exploration, mais peut figer un mauvais type à partir du premier document. En production, les champs métiers importants sont déclarés dans des templates versionnés ; les propriétés inattendues sont refusées ou encadrées par des règles explicites. Une dérive de payload devient un rejet observable, pas un nouveau champ silencieux qui augmente le cluster state.
Les analyseurs influencent directement les résultats. Un changement de tokenizer, de synonymes ou de normalisation peut exiger une réindexation pour que les documents existants et les nouvelles requêtes partagent les mêmes règles. La version d’analyseur est donc liée à la version d’index et validée sur un jeu de requêtes métier avant la bascule.
Réindexer derrière un alias sans coupure
Un changement incompatible crée un nouvel index configuré avant le chargement : settings, mappings, analyseurs, nombre de shards, replicas et alias prévus. L’API de réindexation copie des documents, mais ne transfère pas automatiquement toute cette configuration. Le candidat porte un nom versionné ; les applications lisent un alias stable.
Le chargement initial part d’un watermark ou d’un snapshot cohérent de la source. Pendant qu’il s’exécute, les changements continuent d’arriver. Le pipeline conserve ces deltas, puis les rejoue sur le candidat jusqu’à rattraper la production. Une double écriture non ordonnée ne remplace pas cette stratégie : elle peut appliquer des versions différentes sur les deux index.
La bascule d’alias intervient après les contrôles de volume, de suppressions, de mapping et de recherche. L’ancien index reste disponible pendant une fenêtre de retour. Le rollback remet l’alias sur l’index précédent si aucun nouvel état incompatible n’empêche ce retour ; sinon le système stoppe les nouvelles écritures et réconcilie les deltas avant de revenir.
Utiliser le Bulk API sans masquer les rejets
Le Bulk API réduit le coût réseau en regroupant plusieurs opérations, mais sa réponse doit être inspectée élément par élément. Une requête reçue avec succès peut contenir des indexations, mises à jour ou suppressions refusées. Le worker associe chaque item à son identifiant métier, son action et sa cause, puis ne confirme que les effets réellement acceptés.
La taille du lot est pilotée par le poids, la latence, les rejets et la pression du cluster, pas par un nombre choisi une fois pour toutes. Les retries reprennent uniquement les items transitoires avec backoff et gigue. Un mapping invalide, une donnée trop longue ou un droit insuffisant rejoint une quarantaine ; relancer le lot complet multiplierait les écritures et cacherait le défaut permanent.
Le paramètre de refresh répond à un besoin de visibilité, pas à une habitude. Le comportement par défaut convient aux flux ordinaires. Lorsqu’un parcours doit rechercher juste après une écriture, refresh=wait_for attend le prochain refresh sans forcer systématiquement la création de petits segments. Le seuil d’usage reste borné pour ne pas transformer chaque document en synchronisation coûteuse.
Synchroniser créations, mises à jour et suppressions
Un événement transporte l’identité, la version de source, le type d’effet et l’horodatage métier. Le worker relit éventuellement la source pour construire le document courant, puis compare la version avant d’écrire. Un webhook ou un message accélère la propagation ; il ne remplace pas la source ni la règle d’ordre.
Les suppressions exigent une stratégie spécifique. Une suppression physique peut être publiée comme tombstone avec identité et version, ou détectée lors d’une réconciliation. Sans ce signal, un document disparu de la base reste éternellement recherchable. Une réindexation complète vers un index vide corrige le problème, mais attendre chaque migration pour retirer les fantômes n’est pas un run acceptable.
Les mises à jour partielles sont utilisées seulement si leurs invariants sont clairs. Reconstruire le document complet simplifie souvent la cohérence entre champs calculés. Une modification de prix peut aussi changer une facette, une promotion et un tri ; envoyer uniquement le champ qui a déclenché l’événement laisserait un document hybride.
Rattraper les écarts que les événements ont manqués
Aucun bus ne dispense d’une réconciliation. Une notification peut être perdue, un worker peut confirmer trop tôt, une règle de filtrage peut exclure un dossier ou un opérateur peut corriger la source pendant une panne. Le rapprochement parcourt une fenêtre de données par version, compare les identités et réémet uniquement les différences.
Le nombre total de documents est un premier signal, pas une preuve. La balance ventile par tenant, type, statut ou partition métier, puis compare des agrégats et des échantillons déterministes. Elle vérifie aussi les documents présents uniquement dans l’index, car une égalité de volume peut masquer autant de manquants que de fantômes.
Les écarts portent un motif et une action : indexer, supprimer, attendre une source, corriger le mapping ou exclure selon une règle publiée. Le seuil de tolérance dépend du parcours. Zéro fantôme peut être exigé pour un produit retiré, tandis qu’un retard de quelques minutes reste acceptable pour une recherche éditoriale non critique.
Tester la pertinence autant que la complétude
Les tests techniques vérifient transformation, mapping, ordre, idempotence, Bulk partiel et suppression. Les tests de recherche utilisent un corpus versionné avec requêtes, filtres et résultats attendus. Ils couvrent termes rares, fautes prévues, accents, synonymes, tri, facettes, disponibilité et droits d’accès.
La qualité ne se résume pas au premier résultat. Certaines requêtes exigent la présence d’un produit dans les dix premiers ; d’autres refusent qu’un contenu obsolète apparaisse, même plus bas. Les seuils sont reliés à un besoin utilisateur et comparés entre l’index servi et le candidat.
Cas concret : une nouvelle analyse améliore « canapé convertible » mais fait disparaître une référence recherchée par son SKU exact. Le score moyen peut monter tandis qu’un parcours support se dégrade. La recette conserve donc plusieurs familles de requêtes et bloque l’alias lorsqu’une exigence critique régresse.
Observer fraîcheur, erreurs et santé de l’index
Les métriques de pipeline suivent débit, latence, taille des lots, items rejetés, retries, profondeur, âge du plus ancien événement et avance du watermark. Les métriques de projection suivent documents par partition, suppressions en attente, version de mapping et écarts de réconciliation. Les métriques de recherche suivent latence, erreurs, timeouts et requêtes critiques.
La santé du cluster reste nécessaire, mais un cluster vert ne prouve pas la fraîcheur métier. Le tableau rapproche allocation des shards, pression d’indexation, merges et latence avec le retard de synchronisation. Une alerte décrit l’action attendue : ralentir le backfill, suspendre un mapping, augmenter la capacité ou basculer en lecture seule.
Chaque log transporte businessId, index logique, version de schéma, lot, corrélation et résultat par item. Les payloads sensibles ne sont pas recopiés. Le support peut retrouver un document, sa source et la dernière décision d’indexation sans avoir des privilèges d’administration sur tous les index.
Donner au support une reprise sans commande dangereuse
Le runbook part du symptôme : document absent, résultat obsolète, doublon, facette incohérente ou lot en retard. Il indique comment retrouver la source, la version indexée, les événements et les rejets. Une commande de réindexation ciblée passe par le même pipeline et produit une trace ; elle ne modifie pas directement _source.
Les actions autorisées sont bornées : rejouer un document, rejouer un lot, suspendre une source, reprendre une quarantaine ou remettre un alias selon la procédure. Une réindexation totale n’est pas la réponse par défaut à un seul écart. Elle consomme de la capacité, retarde les corrections prioritaires et peut reproduire le défaut si la transformation n’a pas été réparée.
Le support exerce le rollback avant la production. Il vérifie que l’ancien index existe, que l’alias est la seule adresse utilisée par les lecteurs et que les deltas peuvent être rejoués. Le compte technique possède les privilèges minimaux : écriture sur les candidats prévus, lecture utile et gestion d’alias seulement lorsqu’elle est nécessaire au rôle.
Savoir quand Elasticsearch est justifié
Elasticsearch devient pertinent pour la recherche plein texte, les filtres combinés, les facettes, la géolocalisation ou des agrégations qui dépassent le rôle de la base transactionnelle. Il apporte de la valeur lorsqu’un index éventuellement cohérent est accepté et que l’équipe possède la synchronisation, le mapping et le run associés.
Il faut différer le projet si la source change sans identité stable, si les suppressions ne sont pas observables ou si le besoin est une lecture exacte immédiatement après chaque transaction. Ajouter un moteur de recherche dans ce contexte crée une seconde représentation impossible à réconcilier. La priorité revient au contrat de données et aux cas d’usage.
Une requête SQL ou un moteur intégré peut suffire pour un petit volume, quelques filtres et une équipe réduite. Le coût complet d’Elasticsearch inclut cluster, mappings, réindexations, sécurité, sauvegarde, surveillance et astreinte. La décision compare ce coût au gain de recherche, pas à une simple démonstration plus rapide sur un jeu réduit.
Écrire le contrat d’indexation et d’ordre
L’entrée porte l’identité métier, la version de source, le type d’opération, la version de mapping et la corrélation. La sortie distingue accepté, visible, rejeté, obsolète et mis en quarantaine. Le worker est responsable de la transformation et de l’écriture ; la source est responsable de la vérité ; l’application de recherche est responsable de son comportement lorsque la fraîcheur dépasse le seuil.
Les dépendances, timeouts et retries sont explicites. La file conserve l’ordre nécessaire par identité ou partition, sans imposer un ordre global coûteux. L’idempotence réutilise le même _id et compare la version. La journalisation relie chaque effet au lot Bulk et à sa réponse individuelle.
Une commande de projection vérifiable
L’enveloppe interne reste indépendante du format Elasticsearch. Elle peut être rejouée vers un index candidat, contrôlée avant écriture et rapprochée de la source. La version de document ne doit pas être confondue avec la version de mapping ni avec le numéro de tentative réseau.
{
"operation": "upsert",
"businessId": "SKU-18472",
"sourceVersion": 481,
"mappingVersion": "products-v7",
"targetAlias": "products-search",
"batchId": "catalog-20261001-0042",
"correlationId": "a718..."
}Reprendre un lot sans reculer l’état
Après un timeout, le worker lit le registre ou rejoue l’opération avec la même identité et la même version. Si une version plus récente est déjà indexée, l’ancienne devient obsolète et n’écrit rien. Si le résultat Bulk contenait un rejet permanent, le dossier reste attribué au motif initial au lieu d’entrer dans une boucle.
Le rollback d’alias n’arrête pas la source. Les événements continuent d’être conservés avec leur watermark, puis sont rejoués sur l’index retenu après la décision. Cette séparation entre ingestion et service de recherche permet de revenir sans perdre les changements intervenus pendant l’analyse.
Erreurs fréquentes qui créent des résultats fantômes
Prendre le succès du Bulk pour un succès de chaque item
La réponse globale prouve que le lot a été traité, pas que toutes ses actions ont réussi. Ignorer les résultats individuels crée des trous silencieux. Le pipeline compte succès, conflits, rejets de mapping et erreurs transitoires, puis rattache chaque échec à l’identifiant source et à une décision de reprise.
Un autre raccourci consiste à comparer seulement les volumes. Deux index peuvent contenir le même nombre de documents et des ensembles différents. Les contrôles utilisent des partitions, des identités, des agrégats et des requêtes témoins, avec une attention particulière aux suppressions et aux changements d’éligibilité.
Forcer le refresh ou corriger directement l’index
Forcer un refresh après chaque écriture peut répondre à un test fonctionnel tout en dégradant l’index et la recherche sous charge. La visibilité attendue est définie par parcours ; les flux ordinaires acceptent le refresh périodique, les rares lectures immédiates utilisent un mécanisme borné et mesuré.
Corriger un document directement dans Elasticsearch résout l’écran jusqu’au prochain événement. La source et le pipeline restent faux, l’historique disparaît et la réconciliation peut annuler la correction. Toute reprise passe par la commande d’indexation ou par une réparation de la source, avec le même audit que le flux normal.
Décision de bascule de l’alias
Le candidat devient servi lorsque son schéma, sa complétude, sa fraîcheur et sa pertinence ont franchi les seuils convenus. L’équipe data fournit les preuves techniques ; le métier valide les requêtes critiques ; le support rejoue un rejet et un rollback. Aucun indicateur unique ne remplace cet ensemble.
- D’abord, figer mappings, analyseurs, templates et version de transformation du candidat.
- Ensuite, charger le snapshot, rattraper les deltas et fermer les rejets Bulk permanents.
- Puis, comparer identités, suppressions, agrégats et corpus de recherche avec l’index servi.
- Enfin, basculer l’alias, surveiller la fenêtre prévue et conserver un rollback exercé.
Le go est refusé si le candidat reçoit encore des versions hors ordre, si un type de rejet n’a pas d’owner, si l’application utilise le nom physique de l’index ou si le retour perdrait des deltas. Une réindexation terminée n’est qu’une étape ; la décision porte sur le service rendu.
Plan d’action pour une mise en production progressive
Construire la référence et le pipeline
D’abord, documenter la source, les identités, les suppressions, les requêtes critiques et la fraîcheur acceptable. Un échantillon d’écarts actuels est relu avec le support. Cette référence révèle les règles de transformation implicites et fournit les seuils initiaux de documents manquants, fantômes et obsolètes.
Ensuite, créer templates, mapping et index candidat, puis exécuter le pipeline en lecture comparée. Les Bulk partiels, versions anciennes et tombstones sont provoqués. La réconciliation fonctionne avant le chargement complet. Les tableaux de bord et alertes montrent les motifs de rejet, pas seulement le débit total.
Rattraper, basculer et retirer sans précipitation
Puis, lancer le backfill avec un budget de capacité inférieur au trafic prioritaire. Le watermark et les deltas permettent de mesurer le rattrapage. Le corpus de recherche compare ancien et nouvel index sur des requêtes réelles anonymisées. Chaque divergence critique reçoit une décision avant le changement d’alias.
Enfin, basculer sur une fenêtre observable, sans arrêter la file d’événements. Le support surveille fraîcheur, rejets et requêtes critiques. L’ancien index reste en lecture pendant le délai de retour, puis il est protégé contre les écritures et supprimé seulement après confirmation que les sauvegardes et la reconstruction ont été testées.
Après la production, une revue périodique contrôle les champs dynamiques, les mappings inutilisés, la taille des documents, les requêtes lentes et les partitions déséquilibrées. Chaque changement d’analyseur ou de modèle suit le même parcours de candidat, de comparaison et de bascule ; l’alias n’est jamais modifié par une commande improvisée.
Approfondir mapping, reprise et observabilité
La qualité du document dépend des conversions en amont. Le dossier sur le mapping de données API aide à traiter absence, null, enums et versions. Les retries, backoff et circuit breakers complètent la stratégie pour les erreurs Bulk transitoires et la pression du cluster.
Pour la synchronisation continue, webhook ou polling détaille notification et réconciliation. L’audit trail d’intégration structure enfin les preuves de mapping, de lot, d’alias et de reprise sans transformer les logs en copie des données sources.
Conclusion : une recherche rapide et explicable
Elasticsearch est fiable lorsque l’index reste reconstruisible et que chaque document peut être relié à sa source, sa version et sa transformation. La vitesse de recherche vient après cette chaîne de preuve. Un alias facilite la bascule, mais il ne compense ni un mapping implicite, ni un backfill incomplet, ni des suppressions oubliées.
Le bon dispositif sépare acceptation du Bulk, visibilité après refresh, complétude de la projection et pertinence métier. Il traite chaque rejet, rapproche régulièrement les états et garde l’ancien index tant que le retour n’a pas été exercé. Le support peut alors corriger sans éditer directement le moteur.
Si votre recherche affiche déjà des documents manquants, obsolètes ou impossibles à expliquer, notre accompagnement en intégration API peut reprendre la source, le mapping et les watermarks, bâtir un index candidat et conduire une première bascule d’alias avec comparaison, réconciliation et rollback.
