Le Guide Ultime pour Gérer les Index Elasticsearch via des Commandes API

Gérer les index Elasticsearch via l'API est un travail courant, mais c'est aussi là que se produisent de nombreuses erreurs coûteuses. Un mauvais mapping peut forcer une réindexation. Une suppression par wildcard peut enlever plus que prévu. Un paramètre de réplication qui avait du sens en développement peut laisser la production en jaune après un déploiement.

Un index Elasticsearch n'est pas seulement un seau de documents JSON. Il a des mappings, des paramètres, des alias, des nombres de shards, des nombres de réplicas, des analyseurs et un comportement de cycle de vie. Vous n'avez pas besoin de mémoriser chaque API pour bien le gérer, mais vous avez besoin d'une routine minutieuse : créer des index intentionnellement, inspecter ce qu'Elasticsearch a réellement créé, mettre à jour uniquement les paramètres qui peuvent être modifiés en toute sécurité, et supprimer avec des garde-fous.

Les exemples ci-dessous utilisent des requêtes de style Kibana Dev Tools. Si vous préférez curl, les mêmes chemins et corps JSON s'appliquent contre http://host:9200.

Ce que contient un index

Un index est un espace de noms logique pour les documents. Sous le capot, les shards primaires contiennent les données, et les shards de réplique copient ces données pour la redondance et la capacité de recherche. Le comportement exact par défaut des shards et des répliques peut varier selon la version d'Elasticsearch et le mode de déploiement, alors ne vous fiez pas à votre mémoire. Vérifiez les paramètres dans votre propre cluster.

Les trois éléments que vous inspecterez le plus souvent sont :

• settings, tels que number_of_shards, number_of_replicas, refresh_interval et la configuration d'analyse.
• mappings, qui définissent les types de champs tels que keyword, text, date, long, double, boolean, ip et les champs imbriqués/objets.
• aliases, qui permettent aux applications d'utiliser un nom stable pendant que vous échangez l'index de sauvegarde réel derrière.

Un bon workflow d'API d'index commence avant que le premier document ne soit indexé. Le mapping dynamique est utile pour l'exploration, mais les index de production méritent des mappings explicites pour les champs importants. Si user_id est accidentellement mappé comme text, les agrégations et les filtres exacts deviennent difficiles. Si un timestamp est mappé comme text, les requêtes de plage temporelle ne se comporteront pas comme des requêtes de date. Ces erreurs sont réparables, mais généralement en créant un nouvel index et en réindexant.

Créer un index simple

La plus petite requête de création est :

PUT /my_first_index

Elasticsearch renvoie un accusé de réception si l'index a été créé :

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my_first_index"
}

C'est bien pour un index de test. Pour des données réelles, créez l'index avec les paramètres et les mappings que vous attendez plutôt que de laisser les premiers documents définir la forme.

Créer un index avec des mappings et des paramètres

Voici un index products pratique. Il prend en charge la recherche en texte intégral sur les noms et les descriptions, le filtrage exact sur les ID et les catégories, le tri par date, les filtres de plage numérique et les simples vérifications de disponibilité.

PUT /products-v1
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "refresh_interval": "5s"
  },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "product_id": { "type": "keyword" },
      "sku": { "type": "keyword" },
      "name": {
        "type": "text",
        "fields": {
          "raw": { "type": "keyword", "ignore_above": 256 }
        }
      },
      "description": { "type": "text" },
      "category": { "type": "keyword" },
      "price": { "type": "scaled_float", "scaling_factor": 100 },
      "stock": { "type": "integer" },
      "available": { "type": "boolean" },
      "created_at": { "type": "date" },
      "updated_at": { "type": "date" }
    }
  }
}

Quelques choix ici sont délibérés. product_id, sku et category sont des keyword car vous filtrez, agrégez ou joignez normalement le comportement de l'application autour de valeurs exactes. name est text pour la recherche, avec un sous-champ keyword name.raw pour le tri et la correspondance exacte. price utilise scaled_float afin que les prix puissent être stockés sous forme de valeurs mises à l'échelle en centimes au lieu d'approximations en virgule flottante binaire. dynamic: strict rejette les champs inconnus, ce qui est utile lorsque les mauvaises données du producteur doivent échouer bruyamment.

Ne copiez pas aveuglément le nombre de shards. Trois shards primaires peuvent être trop nombreux pour un petit index et trop peu pour un grand. Le nombre de shards est difficile à modifier après la création sans une migration de type shrink, split ou réindexation, alors dimensionnez-le en fonction du volume de données attendu, de la rétention et du nombre de nœuds.

Inspecter un index après la création

Vérifiez toujours ce qu'Elasticsearch a accepté :

GET /products-v1

Cela renvoie les paramètres, les mappings et les alias. Pour des vérifications ciblées, utilisez des points de terminaison plus étroits :

GET /products-v1/_mapping
GET /products-v1/_settings
GET /products-v1/_alias

Pour une vue compacte en ligne de commande de nombreux index :

GET /_cat/indices/products-*?v

Les colonnes utiles incluent la santé, le statut, le nombre de shards primaires, le nombre de répliques, le nombre de documents, le nombre de documents supprimés et la taille de stockage. Les API _cat sont destinées aux humains. Utilisez les API JSON pour les scripts.

Si vous vérifiez si un champ est correctement mappé, utilisez :

GET /products-v1/_mapping/field/price
GET /products-v1/_mapping/field/name.raw

C'est plus rapide à lire que de faire défiler un grand mapping.

Mettre à jour les paramètres d'index en toute sécurité

Certains paramètres sont dynamiques. Le nombre de répliques est le plus courant :

PUT /products-v1/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Cela peut rendre un cluster vert jaune si vous n'avez pas assez de nœuds de données appropriés. Par exemple, un primaire plus deux répliques a besoin de trois endroits séparés pour placer les copies. Les règles de conscience d'allocation peuvent rendre l'exigence plus stricte.

refresh_interval est un autre paramètre que vous pouvez modifier lors de chargements en masse :

PUT /products-v1/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

Un intervalle d'actualisation plus long peut réduire la surcharge d'indexation, mais les documents nouvellement indexés deviennent visibles pour la recherche moins rapidement. Pour un remplissage en masse, les équipes augmentent ou désactivent souvent temporairement les actualisations, chargent les données, puis restaurent l'intervalle normal et actualisent une fois :

POST /products-v1/_refresh

Certains paramètres sont statiques. number_of_shards ne peut pas être modifié sur un index existant ouvert. Si vous découvrez que le nombre de shards primaires est incorrect, planifiez un nouvel index et une migration.

Modifier les mappings sans vous mentir

Vous pouvez ajouter de nouveaux champs à un mapping :

PUT /products-v1/_mapping
{
  "properties": {
    "brand": { "type": "keyword" }
  }
}

Vous ne pouvez généralement pas modifier le type d'un champ existant sur place. Si price est déjà text, cela ne transformera pas les anciennes valeurs en un champ numérique utile. Créez un nouvel index avec le mapping correct et réindexez :

POST /_reindex
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

Pour les migrations de production, utilisez des alias afin que l'application n'ait pas besoin de connaître la version physique de l'index.

Utiliser des alias pour un accès applicatif plus sûr

Pointez un alias vers la première version :

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v1", "alias": "products" } }
  ]
}

Votre application lit à partir de products. Plus tard, créez products-v2, réindexez les données, testez-les, puis échangez l'alias de manière atomique :

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v1", "alias": "products" } },
    { "add": { "index": "products-v2", "alias": "products" } }
  ]
}

Pour les systèmes à forte écriture, utilisez un alias d'écriture et soyez explicite sur is_write_index :

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v2", "alias": "products-write", "is_write_index": true } }
  ]
}

Les alias sont l'un des moyens les plus simples d'éviter de coder en dur les versions d'index dans les services.

Lister et rechercher les noms d'index avec précaution

Pour inspecter plusieurs index :

GET /products-v1,products-v2/_settings
GET /products-*/_mapping
GET /_cat/indices/products-*?v&s=index

Soyez prudent avec les wildcards larges sur les grands clusters. GET /* ou GET /_all peut produire une réponse énorme et peut inclure des index système ou cachés selon la version, les paramètres et les options de requête. Préférez un modèle étroit comme logs-prod-* ou products-*.

Pour vérifier si un index existe à partir d'un script, utilisez HEAD :

HEAD /products-v1

Un 200 signifie qu'il existe. Un 404 signifie qu'il n'existe pas.

Supprimer des index avec des garde-fous

La suppression est simple :

DELETE /products-v1

Le risque opérationnel n'est pas la syntaxe. Le risque est de supprimer le mauvais index ou de supprimer avant la fin d'un snapshot.

Avant de supprimer, listez exactement ce que le modèle correspond :

GET /_cat/indices/products-old-*?v&s=index

Si la sortie est correcte et que les données sont récupérables ou ne sont plus nécessaires, supprimez le même modèle :

DELETE /products-old-*

De nombreux clusters restreignent les opérations destructives par wildcard avec action.destructive_requires_name. C'est un bon paramètre de sécurité car il bloque les suppressions larges comme DELETE /* à moins que des noms explicites ne soient requis. Même avec cette protection, traitez les opérations de suppression comme des changements de production : confirmez le modèle d'index, confirmez les snapshots et confirmez que l'appelant a les bonnes autorisations.

Préférer les politiques de cycle de vie pour les données de séries temporelles

Les suppressions manuelles sont acceptables pour un nettoyage ponctuel. Pour les logs, les métriques, les traces et autres données de séries temporelles, utilisez Index Lifecycle Management ou les flux de données le cas échéant. Une politique de cycle de vie peut faire basculer un index lorsqu'il atteint un objectif d'âge ou de taille, déplacer les données plus anciennes vers un niveau différent et les supprimer après l'expiration de la rétention.

Cela compte car le nettoyage manuel a tendance à échouer au pire moment. Quelqu'un l'oublie, le disque se remplit, les marqueurs de niveau d'inondation rendent les index en lecture seule, puis l'équipe nettoie sous pression. Les politiques de cycle de vie transforment la rétention en configuration au lieu d'un rappel de calendrier.

Une routine quotidienne simple

Pour un cluster de production, une routine pratique de gestion des index ressemble à ceci :

Vérifiez la santé :

GET /_cluster/health

Listez les index par modèle :

GET /_cat/indices/logs-*?v&s=store.size:desc

Inspectez les paramètres suspects :

GET /logs-prod-2026.05.24/_settings

Vérifiez les mappings avant d'ajouter de nouveaux champs à partir d'une version d'application :

GET /logs-prod-2026.05.24/_mapping

Confirmez les alias avant et après une migration :

GET /_cat/aliases/products*?v

Ce n'est pas un travail glamour, mais cela détecte de nombreux problèmes tôt : mauvais nombres de répliques, champs dynamiques accidentels, alias obsolètes et anciens index qui auraient dû être supprimés.

Erreurs courantes à éviter

Ne laissez pas les valeurs par défaut de développement devenir l'architecture de production. Un cluster à nœud unique, zéro réplique et des mappings dynamiques peuvent être acceptables pour une démo. Ce n'est pas un plan de récupération.

Ne modifiez pas les mappings dans votre tête en supposant qu'Elasticsearch est d'accord. Inspectez le mapping réel.

N'utilisez pas de suppressions par wildcard sans lister d'abord les index correspondants.

Ne définissez pas des nombres de répliques élevés sans suffisamment de nœuds de données et de zones pour les placer.

Ne sautez pas les alias pour les index dont les applications dépendent. La première migration sera beaucoup plus facile si l'application parle déjà à un alias.

Une bonne gestion des index est principalement une répétition disciplinée. Créez avec intention, inspectez ce qui existe, migrez avec des alias, automatisez la rétention et rendez les actions destructives ennuyeusement explicites.

Les modèles comptent plus que les créations ponctuelles

Si vous créez le même type d'index de manière répétée, ne vous fiez pas aux appels manuels PUT /index-name. Utilisez un modèle d'index ou des modèles composables afin que les nouveaux index reçoivent automatiquement les bons mappings, paramètres, alias et politique de cycle de vie.

Une plateforme de logs est l'exemple classique. Si logs-web-2026.05.24 a un mapping @timestamp correct mais que l'index de demain est créé dynamiquement par le premier document, un événement mal formé peut mapper un champ de manière incorrecte. L'erreur peut ne pas apparaître avant que les tableaux de bord échouent ou que les agrégations disparaissent. Les modèles empêchent cette dérive.

Un modèle simple pourrait définir un modèle, des paramètres et des mappings pour les futurs index :

PUT /_index_template/logs_web_template
{
  "index_patterns": ["logs-web-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "service": { "type": "keyword" },
        "level": { "type": "keyword" },
        "message": { "type": "text" },
        "trace_id": { "type": "keyword" }
      }
    }
  }
}

Les modèles sont également plus faciles à examiner dans le code. Mettez-les sous contrôle de version, déployez-les via le même chemin que les modifications d'application et testez-les avant que le basculement ne crée le prochain index de sauvegarde.

Réindexer sans surprendre l'application

La migration d'index la plus propre est généralement : créer un nouvel index versionné, réindexer les données, comparer les comptes et les requêtes d'échantillonnage, puis échanger un alias. Ne pointez pas l'application directement vers products-v1 à moins que vous n'aimiez les changements de configuration d'urgence.

Une migration minutieuse ressemble à ceci :

PUT /products-v2
{
  "mappings": {
    "properties": {
      "product_id": { "type": "keyword" },
      "name": { "type": "text" },
      "price": { "type": "scaled_float", "scaling_factor": 100 }
    }
  }
}

Puis réindexez :

POST /_reindex?wait_for_completion=false
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

En utilisant wait_for_completion=false, vous obtenez un ID de tâche afin de pouvoir surveiller une longue réindexation. Après la fin, comparez les nombres de documents et exécutez des recherches représentatives. Ce n'est qu'ensuite que vous échangez les alias.

Pour les index à forte écriture, réfléchissez aux écritures doubles, aux fenêtres de pause ou à la relecture à partir d'une source de vérité. Les commandes API sont faciles ; le plan de cohérence est le vrai travail.

Sécurité et autorisations

Les API d'index ne devraient pas être disponibles pour chaque utilisateur de l'application. Un service de recherche peut avoir besoin de privilèges de lecture sur un alias. Un ingester de données peut avoir besoin de privilèges de création, d'indexation et d'écriture sur un alias d'écriture. Très peu d'identités devraient avoir des privilèges larges de suppression ou de gestion.

Cela compte car les API d'index sont puissantes. Une information d'identification d'application compromise avec des privilèges manage peut modifier les paramètres de réplication, fermer des index ou supprimer des données. Gardez les privilèges destructifs séparés et faites en sorte que la suppression en production nécessite un workflow d'opérateur plutôt qu'un chemin d'application.

Les conventions de nommage réduisent les erreurs

Utilisez des noms qui encodent le but et le cycle de vie : products-v3, logs-web-2026.05.24, metrics-api-000123 ou des noms de flux de données qui correspondent à la source de données. Évitez les noms vagues comme newindex, test2 ou prod-final. Lors du nettoyage, les noms vagues rendent difficile de savoir ce qui peut être supprimé en toute sécurité.

Pour les index de séries temporelles, utilisez des formats de date cohérents et évitez de mélanger l'heure locale et les hypothèses UTC. Pour les index métier versionnés, gardez l'alias stable et laissez la version physique de l'index changer derrière. Une convention de nommage ennuyeuse est une fonctionnalité de sécurité opérationnelle.