Réindexation des flux de données en raison de conflits de mapping

En cas de conflits de mapping de champs, qu'ils soient conformes à la norme Elastic Common Schema (ECS) ou spécifiques à la source de données, une réindexation des données à l'aide des outils de développement s'avère nécessaire. Ces conflits peuvent avoir un impact négatif sur les fonctions en aval après l'ingestion, entraînant potentiellement des résultats inexacts ou empêchant l'utilisation de l'ensemble des données dans des fonctionnalités telles que les visualisations, les tableaux de bord, l'application Security et les agrégations. Cet article de blog détaille les étapes de ce processus de réindexation.

Le contenu de ce blog a été développé et vérifié à l'aide des versions Elastic 9.2.8 et 8.19.14, ainsi que des versions Filestream Integration 2.3.0 et 1.2.0.

Remarque importante : selon votre environnement, certaines étapes peuvent nécessiter des modifications spécifiques. De plus, sachez que les modèles dynamiques ont été supprimés du modèle de composants @package à compter de la version 2.3.3 de Filestream Integration.

Avant de commencer le processus de réindexation, il est important de prendre en compte l'allocation actuelle de stockage dans votre environnement. Les étapes décrites ci-dessous impliquent la création d'une copie de l'index sous-jacent existant, qui résidera temporairement dans le niveau hot.

Niveaux de données Elasticsearch

• Hot : le niveau hot est le point d'entrée d'Elasticsearch pour les données temporelles, stockant les données les plus récentes et les plus fréquemment recherchées. Les nœuds du niveau hot nécessitent des lectures et des écritures rapides, ce qui requiert davantage de ressources et un stockage plus rapide (SSD). Ce niveau est obligatoire et de nouveaux index de flux de données y sont automatiquement attribués.
• Warm : les données temporelles peuvent passer au niveau warm une fois qu'elles sont interrogées moins fréquemment que les données récemment indexées du niveau hot. Le niveau warm contient généralement les données des dernières semaines. Les mises à jour sont toujours autorisées, mais elles sont probablement peu fréquentes. Les nœuds du niveau warm n'ont généralement pas besoin d'être aussi rapides que ceux du niveau hot. Pour la résilience, les index du niveau hot doivent être configurés pour utiliser une ou plusieurs répliques.
• Cold : les données rarement consultées peuvent être déplacées du niveau warm vers le niveau cold. Celui-ci, tout en restant interrogeable, privilégie la réduction des coûts de stockage à la vitesse de recherche. Il est également possible d'y stocker des index classiques avec des répliques plutôt que des instantanés interrogeables, ce qui permet d'utiliser du matériel moins coûteux pour les données anciennes sans pour autant réduire l'espace disque requis par rapport au niveau warm.
• Frozen : les données rarement interrogées ou qui ne le sont plus passent du niveau cold au niveau frozen pour la durée restante de leur cycle de vie. Ce niveau utilise un référentiel de snapshots et des index partiellement assemblés pour stocker et charger les données, réduisant ainsi le stockage local et les coûts tout en permettant la recherche. Les recherches sur le niveau frozen sont généralement plus lentes que sur le niveau cold, car Elasticsearch peut avoir besoin de récupérer les données frozen depuis le référentiel de snapshots. Nous vous recommandons d'utiliser des nœuds dédiés au niveau frozen.

Prérequis : déterminer quels champs présentent des conflits

Pour déterminer les champs qui présentent des conflits de mapping, accédez à Stack Management -> Data Views -> logs-* (la data view logs-* est la hiérarchie la plus élevée des données présentes avec le préfixe logs-). Si des conflits sont présents, un encadré jaune s'affiche. Vous pouvez cliquer sur View conflicts ou, sous la zone Field type à côté de la zone Search, sélectionnez le conflit.

Cliquez sur le bouton jaune Conflict pour voir quels index sont associés à quels types de mapping.

Cette situation (où le champ est mappé à la fois en tant que keyword et en tant que long) se produit généralement parce que les données ont été ingérées avant qu'un type de mapping spécifique ait été défini dans le modèle de composants pour le flux de données concerné. Dans de tels cas, Elasticsearch tente de définir le mapping en fonction de ses modèles dynamiques.

Pour déterminer quel mapping est approprié pour le champ et si le champ est un champ ECS, une vérification avec la référence des champs ECS est nécessaire. Si le champ en question n'est pas un champ ECS, sa valeur doit être examinée pour déterminer le mapping approprié.

Si un champ, comme log.offset dans cet exemple, n'est pas documenté dans l'ECS, les étapes suivantes consistent à examiner la valeur du champ, à déterminer quel type de mapping conflictuel possède le plus d'index sous-jacents, et à examiner les modèles de composants des autres index.

En général, le type de mapping associé au plus grand nombre d'index est le bon, mais nous vous recommandons de vérifier la valeur du champ concerné pour le confirmer. Pour confirmer la validité d'un type de mapping (par exemple, long), vous devez également vérifier que la valeur du champ est appropriée pour ce type. Cette vérification peut être effectuée en utilisant Discover pour rechercher le champ en question. L'examen d'autres flux de données contenant le même champ peut également apporter une confirmation supplémentaire.

Pour examiner les valeurs présentes pour le champ qui présente le problème de mapping, revenez au bouton jaune Conflict indiqué précédemment, cliquez sur le bouton Conflict, sélectionnez l'un des index sous-jacents et collez-le dans une session Discover . Votre instruction Kibana Query Language (KQL) devrait ressembler à la capture d'écran suivante, pour inclure le délimiteur de champ _index:.

Préparation du nouveau modèle de composants personnalisé d'index sous-jacent

Pour résoudre le conflit de mapping dans le flux de données, examinez d'abord le modèle de composants @package pertinent. Vous trouverez ceci sous Stack Management -> Index Management -> Component Template. Cherchez le flux de données et sélectionnez le lien @package correspondant. Ce modèle contient des mappings prêts à l'emploi pour les champs et, bien que les incohérences de mapping soient rares, il est possible que le type le plus approprié ait été ignoré.

Vérifiez le modèle pour vous assurer qu'il contient l'imbrication et le mapping de champs nécessaires pour le champ en question. Par exemple, si le modèle liste log.offset comme keyword par erreur, la source du problème est ici.

Important : comme il n'est pas recommandé de modifier les modèles @package/managed, vous devez utiliser ou créer un modèle de composants @custom pour corriger le type de mapping (par exemple, pour log.offset) pour toutes les données futures.

• Nous ne recommandons pas de modifier les modèles @package/managed, car lorsque vous mettrez à jour l'intégration vers une version plus récente, toutes les modifications que vous apporterez au modèle @package seront remplacées. C'est pourquoi nous recommandons d'utiliser les modèles @custom.
• Si un flux de données rencontre des conflits de mapping, vous devez ajouter tous les champs manquants (imbrications ou mappings ECS et non-ECS) au modèle de composants @custom du flux de données. Créez ce modèle s'il n'existe pas encore et veillez à spécifier le type de mapping correct pour le champ.
• Si plusieurs conflits sont présents dans votre data view, appliquez simultanément tous les mappings manquants nécessaires au flux de données afin que la réindexation ne soit effectuée qu'une seule fois. L'ajout d'entrées pour le typage correct des données dans le modèle de composants @custom garantira que toute ingestion ultérieure de données suivra les mêmes règles de mapping.

Pour créer le modèle de composants @custom (ou vérifier qu'il est utilisé et renseigné), accédez ) Index Templates, saisissez le nom du flux de données en question et cliquez sur le modèle @custom approprié utilisé par le flux de données. Si le modèle n'est pas encore créé, une case jaune apparaît, vous permettant de le créer via l'interface utilisateur.

La capture d'écran ci-dessous montre la page suivante après que l'option Create component template a été sélectionnée. Laissez les paramètres par défaut tels quels sur la première page et cliquez sur Mappings ou Next jusqu'à atteindre la page Mappings.

Pour définir explicitement le mapping d'un nouveau champ entrant ou pour mettre à jour un champ présentant un conflit de mapping, lorsque le flux de données est réinitialisé en raison d'une configuration définie dans la politique de cycle de vie de l'index, une entrée est nécessaire pour le champ dans lequel le conflit existe.

La procédure suivante permet de définir le mapping du champ log.offset dans le modèle de composants @custom pour le flux de données filestream. Répétez les étapes pour ajouter des champs personnalisés ou mettre à jour les champs nécessaires du @package avec les mappings appropriés, si nécessaire, pour cet ensemble de données. Dans cet exemple, en définissant le décalage sur Long, le type de champ sera Numeric et le type numérique sera Long. Cliquez sur Add field, puis en dehors de la zone pour continuer.

Une fois tous les champs nécessaires ajoutés, cliquez pour vérifier, puis sélectionnez Create component template lorsque vous êtes prêt. log.offset sera défini sur long pour toutes les nouvelles données ingérées à partir de cette étape.

Création de la nouvelle structure de l'index sous-jacent

Le nouvel index sous-jacent doit comporter les mappings existants du modèle de composants du flux de données, ainsi que le modèle de composants ECS ecs@mappings. Le modèle de composants ecs@mappings est appliqué après le composant du flux de données en tant que catchall pour les mappings supplémentaires qui n'ont potentiellement pas été capturés dans les modèles de composants précédents.

Accédez à l'onglet navigateur pour les mappings @package du flux de données. (Stack Management -> Index Management -> Component Template -> logs-filestream.generic@package -> Manage -> Edit.) Une fois sur place, cliquez sur la section Review, puis sur Request, et enfin sur le bouton Copy à droite. Le contenu JSON du modèle de composants copié garantit la conservation des mappings de champs et des paramètres restants pendant la mise à jour du mapping de champ log.offset. Ce JSON constituera la structure sous-jacente de l'index nouvellement réindexé.

Important : si le JSON du modèle n'avait pas été copié et que l'opération de réindexation se soit poursuivie, le conflit log.offset aurait été résolu, mais de nouveaux conflits seraient survenus avec l'intégration, car l'intégrité des mappings actuels n'a pas été respectée, créant un double travail pour résoudre le problème initial.

Ouvrez un deuxième onglet de navigateur, accédez aux outils de développement et collez le contenu copié. Ensuite, pour nettoyer ce qui a été collé :

Modifications de la demande

1. Nom de l'index : remplacez _component_template/logs-filestream.generic@package par le nom de l'index sous-jacent que vous souhaitez réindexer, en ajoutant -1 à la fin. Par exemple, utilisez PUT <backing index to reindex>-1.

• Le -1 ajouté indique une réindexation et ne sera pas en conflit avec les paramètres de substitution ILM par défaut, qui sont basés sur la date de création de l'index.

2. Paramètres : supprimez la ligne "template" (ligne 3), ainsi que la toute dernière accolade fermante de l'ensemble de la charge utile JSON ; la ligne 3 doit commencer par "settings": {.

• Remplacez le contenu interne de la section des paramètres par "index.codec": "best_compression". Cette action appliquera la meilleure compression d'Elastic à l'index lors de sa création.
• Ajoutez "index.lifecycle.name": "logs", ainsi qu'une ligne pour "index.lifecycle.rollover_alias": "".
  1. L'entrée "index.lifecycle.name": "logs" appliquera la politique ILM des logs au nouvel index sous-jacent. Modifiez le nom de la politique ILM si vous n'utilisez pas de logs.
  2. Le "index.lifecycle.rollover_alias": "" est vide, car cet index sous-jacent ne sera par reconduit ; ce paramètre est néanmoins nécessaire pour éviter les erreurs de substitution ILM dans la phase ILM qui suit la phase hot.

3. Structure : la requête doit désormais inclure à la fois une section Settings et une section Mappings. Dans "mappings": {, vous devriez trouver "dynamic_templates" et une section "properties" contenant des champs codés en dur et leurs mappings.

4. Modification des modèles dynamiques : la section des modèles dynamiques actuels contient des entrées de champs qui peuvent être remplacés lorsque les modèles dynamiques ecs@mappings sont ajoutés ensuite, ce qui génère une redondance et des lignes supplémentaires qui ne sont pas nécessaires.

• Supprimez toutes les sections de "dynamic_templates" sauf la deuxième intitulée "_embedded_ecs-data_stream_to_constant": {.
• Répétez le même processus que celui décrit ci-dessus, en rassemblant les mappings dynamiques pour le modèle de composants @package, mais cette fois-ci les mappings dynamiques pour le modèle de composants ecs@mappings.
  • Il peut être plus simple de copier l'intégralité du contenu des mappings depuis l'interface utilisateur pour le modèle de composants ecs@mappings, de coller dans la section Dev Tools dynamic_templates fonctionnelle, et de supprimer les lignes dupliquées et inutiles là où c'est approprié. Incluez ces contenus de paramètres de modèle dynamique après l'entrée "_embedded_ecs-data_stream_to_constant": {. La section dynamic_templates doit être très proche des exemples de contenus ci-dessous dans Dev Tools.
• Si les dynamic_templates ne sont pas inclus/supprimés, d'autres champs (voir la capture d'écran ci-dessous) comporteront des mappings en double : text et keyword par rapport aux mappings appropriés, si la section dynamic_templates n'a pas été retirée. Ce qui reste devrait être la section "properties" sous "mappings". Cela créera également des problèmes dans la data view puisque les champs ont été mappés en double (s'ils n'ont pas déjà été mappés de cette façon) et provoquera des conflits de mapping supplémentaires.

5. Suppression des métadonnées : supprimez la dernière section étiquetée "_meta", ainsi que la section étiquetée "version", si elle est présente.

6. Formatage : indentez automatiquement les sections restantes et ajustez ou supprimez les accolades inutiles qui pourraient empêcher une exécution correcte.

7. Modification du mapping : accédez à la section "properties", recherchez "log", puis localisez "offset" imbriqué en dessous. Changez le type de keyword pour long, puis supprimez l'entrée de ligne (virgule incluse) étiquetée "ignore_above": 1024,. Si plus d'une entrée a été ajoutée au modèle de composants @custom créé précédemment, incluez-les ici.

La vue console de vos outils de développement devrait maintenant être semblable à l'exemple ci-dessous.

Une fois que votre console ressemble à l'exemple (avec tous les champs personnalisés supplémentaires inclus et les valeurs personnalisées spécifiques à votre environnement), exécutez la commande pour créer la structure du nouvel index sous-jacent, en prenant le temps de résoudre les erreurs éventuelles.

Démarrer le processus de réindexation

Une fois la structure du nouvel index sous-jacent correctement créée, l'étape suivante consiste à réindexer et à résoudre les conflits de mapping.

Important : si l'index sous-jacent qui présente le conflit de mapping est l'index le plus récent et l'index d'écriture actuel (par exemple, si le numéro final de l'index sous-jacent est -000001), le flux de données doit être remplacé. Le remplacement du flux de données est nécessaire, car l'index d'écriture actuel, dans lequel des documents sont ingérés, est un index sous-jacent actif et ne peut pas être modifié.

Maintenant que le mapping correct a été appliqué au dernier index d'écriture via le modèle de composants @custom créé précédemment, tous les nouveaux documents refléteront ce changement.

Ceci s'effectue en exécutant ce qui suit :

Par exemple :

La réindexation consiste à copier les données d'un index sous-jacent existant vers un nouvel index dans le cadre de la même convention de dénomination, généralement pour appliquer les modifications nécessaires. Ces modifications peuvent inclure des mises à jour d'un modèle de composants ou l'ajout d'un nouveau pipeline d'ingestion pour les données à traiter.

Ensuite, les données seront copiées depuis l'index sous-jacent dont les mapping sont incorrects vers un nouvel index sous-jacent. L'index sous-jacent initial a été remplacé, ce qui signifie qu'aucun nouveau document ne peut y être ajouté. Le nouvel index sous-jacent suivra la même convention de dénomination, ce qui préserve la visibilité et l'intégrité des données tout en appliquant la politique ILM adéquate, mais il contiendra le suffixe -1 pour indiquer qu'il a été réindexé.

Ajustez les noms d’index selon les besoins et collez le code suivant dans la console. En incluant wait_for_completion=false, vous pouvez suivre la progression de la copie des documents, ce qui permet d'estimer le temps de réindexation restant. Sans ce paramètre, vous ne pourrez pas suivre le statut à l'aide de la commande GET _tasks ci-dessous et ne pourrez vérifier le nombre de documents dans l'index de sauvegarde plus récent qu'à l'aide de la commande GET <backing index name>-1/_count.

Important : en cas de problèmes pendant le processus de réindexation, ne relancez pas la commande de réindexation, car cela redémarrera le processus et créera des enregistrements en double dans l'index se terminant par -1. Si un redémarrage est nécessaire, supprimez d'abord l'index avec -1 à la fin, puis exécutez la commande PUT précédente pour recréer le nouveau shell de l'index sous-jacent.

À l'exécution, la réponse inclura un identifiant de tâche. Vous pouvez surveiller la progression de la réindexation en utilisant cet ID avec la commande : GET _tasks/<task ID>.

La durée de la réindexation dépend du volume de données dans l'index initial. L'achèvement peut être suivi en recherchant "completed": true lors de l'exécution de la commande GET, ce qui devrait produire une sortie similaire.

GET _tasks/<task ID>

Le processus de réindexation étant maintenant terminé pour le nombre de documents, l'étape suivante consiste à vérifier que les mappings entre le nouvel index sous-jacent et le champ spécifique en question sont corrects.

Par exemple :

Vous pouvez vérifier que le mapping pour log.offset est conforme à celui indiqué ci-dessous. Pour confirmer que les autres champs n'ont qu'une seule entrée de mapping (et non text et keyword), comparez-les à un champ qui ne faisait pas partie de la section de modèle dynamique dans la commande PUT précédente.

Si l'index de support en cours de réindexation contient un grand nombre de documents, il est utile de vérifier l'état de ces documents copiés vers le nouvel index de support ; cela peut être fait à l'aide des deux commandes suivantes des outils de développement pour comparer les comptes.

GET .ds-logs-filestream.generic-default-2026.04.14-000001/_count

GET .ds-logs-filestream.generic-default-2026.04.14-000001-1/_count

Une fois que vous avez vérifié que les nombres correspondent et que les mappings corrects sont présents, mettez à jour le flux de données pour inclure le nouvel index sous-jacent afin d'éviter que la gestion des index comporte un index sous-jacent orphelin auquel la politique ILM ne s'appliquera jamais.

• Si l'opération aboutit, une confirmation de réussite est renvoyée.

Vérifiez que le nouvel index sous-jacent a été ajouté à l'aide de la commande suivante, en vous assurant que le paramètre ilm_policy est correct :

Vérifiez l'état ILM de l'index sous-jacent suivant avec cette commande :

• Vous constaterez que l'index est en mode hot, ce qui est normal car il a été créé très récemment (consultez la ligne 8 ou 10).

Exécutez la procédure suivante pour faire passer l'index de sauvegarde du niveau chaud au niveau approprié suivant la phase chaude de la stratégie ILM pour ce flux de données. Les valeurs spécifiques pour phase, action et name dans le current_step ci-dessous peuvent être consultées respectivement à partir des lignes 11, 13 et 15, dans la capture d’écran fournie ci-dessus.

La valeur next_step indique la phase ILM ou le niveau de données ultérieur auquel l'index passera.

Par exemple :

• Ce n'est pas nécessaire, mais par mesure de sécurité, vous pouvez exécuter à nouveau la commande _ilm/explain pour vous assurer que l'index sous-jacent est passé à la phase suivante et n'est plus en phase hot.

Lorsque les conditions suivantes sont remplies, vous pouvez supprimer en toute sécurité l'index sous-jacent initial qui présentait des conflits de mapping :

1. Un nouvel index sous-jacent a été correctement créé.
2. Les documents ont été déplacés vers le nouvel index et le nombre de documents correspond.
3. Les mappings ont été corrigés (ceux spécifiques au flux de données et ceux d'ECS).
4. Le flux de données intègre le nouvel index sous-jacent.
5. La politique ILM a été appliquée et a permis à l'index de sortir de sa phase chaude.

Important : sinon, avant de supprimer l'index initial, vous pouvez consulter la page Data Views. Sélectionnez logs-* et vérifiez que l'index sous-jacent réindexé (qui se termine par -1) apparaît maintenant dans la section long. L'index sous-jacent initial devrait toujours être présent sous keyword. Si l'index sous-jacent initial réindexé ne se trouve pas dans la section long, revenez en arrière pour vérifier les étapes précédentes et effectuer les corrections nécessaires.

Par exemple :

Après avoir résolu les conflits, retournez à la page Data Views et sélectionnez logs-*. Si le conflit était uniquement lié à log.offset, aucun conflit ne devrait plus être listé. Si d'autres conflits étaient présents, l'index sous-jacent initial ne devrait plus apparaître dans la liste des conflits, et le nouvel index sous-jacent devrait désormais figurer dans la section long.

Vous pouvez également vérifier dans Discover que le champ log.offset affiche désormais les icônes appropriées.

Poursuivez ce processus en répétant les étapes ci-dessus pour chaque index de sauvegarde présentant un conflit de mapping, jusqu'à ce que tous soient résolus avec succès.

Références :

• Référence de champ ECS
• Réindexer les documents

Conclusions

En suivant les étapes décrites dans cet article, vous résoudrez les conflits de mapping et vous assurerez que toutes les nouvelles données sont correctement mappées. Pour ce faire, vous lierez les modèles de composants nécessaires à votre source de données. Ce processus permet non seulement de corriger les problèmes immédiats, mais aussi d'établir une méthode sécurisée et reproductible pour gérer les modifications de schéma à mesure que vos données et vos besoins évoluent.