Réindexer Algolia après une migration de 80 000 pages sans doublon

wp algolia index peut sembler suffisant pour réindexer un site. Sur un site de documentation technique qui vient de migrer 80 000 pages d’une arborescence à une autre, cette commande brute présente un risque concret : pendant toute la durée de la réindexation, l’index de recherche live contient un mélange d’anciennes et de nouvelles URL, ce qui expose aux utilisateurs des résultats qui pointent vers des pages qui n’existent plus.

Ce tutoriel détaille la méthode utilisée pour reconstruire l’index par lots sur ce site, sans exposer d’incohérence à la recherche pendant la bascule et sans laisser un index temporaire facturé indéfiniment sur le plan Algolia.

Étape 1 — Créer un index temporaire, pas modifier le live

La première règle est de ne jamais réindexer directement dans l’index de production consulté par les visiteurs. À la place, on crée un index miroir, généralement suffixé _tmp, qui reçoit l’intégralité du nouveau contenu avant toute bascule :

$client = \Algolia\AlgoliaSearch\SearchClient::create(
    ALGOLIA_APP_ID,
    ALGOLIA_ADMIN_KEY
);
$tempIndex = $client->initIndex( 'documentation_tmp' );

Cet index temporaire n’a aucun visiteur, aucune requête de recherche dessus : il peut rester incomplet pendant des heures sans que personne ne le remarque.

Étape 2 — Découper la réindexation en lots de 1 000 objets

Envoyer 80 000 objets en un seul appel saveObjects expose à des timeouts et complique la reprise en cas d’échec partiel. La pratique retenue a été de découper la requête WP_Query en pages de 1 000 posts, avec un identifiant de reprise stocké dans une option, pour pouvoir relancer le script sans repartir de zéro en cas d’interruption :

$paged = (int) get_option( 'algolia_migration_paged', 1 );
$query = new WP_Query([
    'post_type'      => 'documentation',
    'posts_per_page' => 1000,
    'paged'          => $paged,
    'no_found_rows'  => true,
]);

$records = array_map( 'build_algolia_record', $query->posts );
$tempIndex->saveObjects( $records, [ 'objectIDKey' => 'objectID' ] );

update_option( 'algolia_migration_paged', $paged + 1 );

Étape 3 — Vérifier le nombre d’objets avant la bascule

Avant de considérer l’index temporaire comme prêt, on compare son nombre d’objets à celui attendu depuis la base WordPress, via l’API getSettings couplée à une requête de comptage. Sur ce projet, deux lots avaient échoué silencieusement à cause d’un timeout réseau : sans ce contrôle, l’index temporaire aurait été basculé en production avec 2 200 fiches manquantes.

1. Compter les enregistrements attendus côté WordPress (post_type publié, hors brouillons).
2. Interroger l’index temporaire pour connaître son nombre d’objets réel.
3. Relancer uniquement les lots manquants, identifiés par leur plage d’ID.

Étape 4 — Basculer sans doublon avec moveIndex

La bascule elle-même utilise l’opération moveIndex de l’API Algolia, qui renomme atomiquement l’index temporaire pour qu’il devienne l’index de production, en écrasant l’ancien en une seule opération transactionnelle côté Algolia. Cette approche élimine tout risque de doublon ou de fenêtre où deux index coexistent visibles :

$client->moveIndex( 'documentation_tmp', 'documentation' );

Contrairement à un clearIndex suivi d’un nouveau saveObjects, cette méthode ne laisse jamais l’index de production vide, même une fraction de seconde.

Étape 5 — Nettoyer l’index fantôme

Après un moveIndex réussi, l’index temporaire n’existe plus : il a été renommé, pas dupliqué. Le point de vigilance porte plutôt sur les tentatives précédentes laissées en échec : sur ce projet, deux index _tmp orphelins issus d’essais interrompus étaient restés actifs plusieurs semaines, chacun facturé au même tarif qu’un index de production actif. Un contrôle mensuel de la liste des index via listIndices permet d’éviter cette facturation fantôme.

En résumé

Réindexer 80 000 pages sans exposer d’incohérence à la recherche repose sur trois principes : ne jamais toucher l’index live directement, découper le travail en lots reprenables, et basculer de façon atomique avec moveIndex plutôt qu’un enchaînement de suppression et de reconstruction. Sur ce site de documentation, la migration complète a pris un peu plus de quatre heures répartie en douze lots, sans qu’un seul visiteur ne voie de résultat de recherche cassé pendant l’opération.