Indexation et mise à jour de documents avec l'API REST d'Elasticsearch

Elasticsearch est un moteur d'analyse et de recherche puissant et distribué qui repose sur une ingestion de données bien structurée. La gestion de ces données implique des opérations fondamentales de Création, Lecture, Mise à jour et Suppression (CRUD), principalement exécutées via son API REST polyvalente. Comprendre comment indexer correctement de nouveaux documents et mettre à jour efficacement ceux qui existent est crucial pour maintenir un magasin de données précis et en temps réel.

Ce guide vous présentera les méthodes HTTP et les points de terminaison d'API essentiels utilisés pour l'indexation de nouveaux enregistrements et la modification de documents existants au sein de votre cluster Elasticsearch. Nous nous concentrerons sur la syntaxe, les charges utiles JSON requises et l'interprétation des codes de réponse pour garantir une gestion des données fluide.

---

Prérequis

Avant de continuer, assurez-vous d'avoir :

• Un cluster Elasticsearch actif et en cours d'exécution.
• Un outil en ligne de commande capable d'effectuer des requêtes HTTP (comme curl) ou un client HTTP (comme Postman).
• La connaissance du nom de votre index cible.

---

1. Indexation de nouveaux documents

L'indexation est le processus de stockage d'un document JSON dans un index Elasticsearch. Elasticsearch attribue automatiquement un ID unique au document, sauf si un ID est explicitement fourni. La méthode principale pour l'indexation est la méthode HTTP PUT ou POST.

1.1 Indexation avec un ID automatique (POST)

Lorsque vous utilisez POST vers le point de terminaison d'index, Elasticsearch génère un ID de document unique pour vous. C'est souvent la méthode préférée pour l'ingestion initiale de données lorsque les ID sont gérés en interne.

Point de terminaison (Endpoint) : POST /{index_name}/_doc/

Exemple de requête (utilisant curl) :

curl -X POST "localhost:9200/products/_doc/" -H 'Content-Type: application/json' -d'
{
  "name": "Wireless Mouse X1",
  "price": 25.99,
  "in_stock": true
}
'

Extrait de réponse réussie :

{
  "_index": "products",
  "_id": "c7BwJ3gBpV4wT-eH_aY1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

Le champ result affichant created confirme qu'un nouveau document a été ajouté.

1.2 Indexation avec un ID spécifique (PUT)

Si votre système source fournit un identifiant unique pour le document, vous devez utiliser la méthode PUT ciblant un ID spécifique. Si un document avec cet ID existe déjà, PUT écrasera l'intégralité du document.

Point de terminaison (Endpoint) : PUT /{index_name}/_doc/{document_id}

Exemple de requête : Indexation d'un document avec l'ID 1001.

curl -X PUT "localhost:9200/products/_doc/1001" -H 'Content-Type: application/json' -d'
{
  "name": "Mechanical Keyboard K90",
  "price": 129.99,
  "in_stock": true
}
'

Extrait de réponse réussie :

{
  "_index": "products",
  "_id": "1001",
  "_version": 1,
  "result": "created",
  "_shards": { ... }
}

Conseil sur l'écrasement : Si vous exécutez exactement la même requête PUT à nouveau avec le même ID, le result passera à updated et le numéro _version sera incrémenté.

---

2. Mise à jour de documents existants

La mise à jour de documents est distincte de l'écrasement. Lorsque vous souhaitez uniquement modifier des champs spécifiques dans un document existant sans affecter les champs inchangés, vous utilisez le point de terminaison _update, généralement avec la méthode POST.

2.1 Mises à jour partielles à l'aide de _update

L'API _update est cruciale pour les mises à jour atomiques. Elle nécessite un bloc doc dans la charge utile, qui contient uniquement les champs que vous souhaitez modifier. Elasticsearch récupère le document, fusionne les modifications et le réindexe.

Point de terminaison (Endpoint) : POST /{index_name}/_update/{document_id}

Scénario d'exemple : Nous souhaitons mettre à jour le prix du produit ID 1001 de 129,99 $ à 119,99 $ et le marquer comme étant en rupture de stock.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 119.99,
    "in_stock": false
  }
}
'

Extrait de réponse réussie :

{
  "_index": "products",
  "_id": "1001",
  "_version": 2, 
  "result": "updated",
  "_shards": { ... }
}

Notez que _version est passé de 1 à 2, reflétant la modification.

2.2 Utilisation des mises à jour scriptées

Pour les mises à jour plus complexes, conditionnelles ou mathématiques, Elasticsearch prend en charge le script Painless au sein de l'API _update. Cela vous permet d'effectuer des opérations telles que l'incrémentation de compteurs ou la définition de champs basés sur leurs valeurs actuelles.

Scénario d'exemple : Incrémenter le nombre en stock de 5 pour le document ID 1001.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "script": {
    "source": "ctx._source.stock += params.count",
    "params": {
      "count": 5
    }
  }
}
'

Concept clé du scripting : ctx._source fait référence à la source du document actuel.

Avertissement sur les scripts : Bien que puissants, les scripts complexes peuvent avoir un impact sur les performances. Utilisez des mises à jour de champs simples (doc) chaque fois que possible, car elles sont généralement plus rapides et plus sûres.

---

3. Indexation et mises à jour en masse (Bulk)

Pour les opérations de données à volume élevé, l'envoi de requêtes individuelles pour chaque document est inefficace. Elasticsearch fournit l'API _bulk pour gérer plusieurs opérations d'indexation, de mise à jour ou de suppression dans une seule requête.

3.1 Structure d'une requête en masse (Bulk)

Les requêtes en masse utilisent un format JSON spécifique, délimité par des sauts de ligne (NDJSON). Chaque opération est définie par une ligne de métadonnées (spécifiant l'action, l'index et l'ID facultatif) immédiatement suivie par la source du document (si nécessaire).

Types d'action pour le Bulk : index, create, update, delete.

Exemple de requête en masse (mélange d'indexation et de mise à jour) :

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'

{"index": {"_id": "2001"}}
{"name": "USB-C Hub", "price": 45.00, "in_stock": true}
{"update": {"_id": "1001"}}
{"doc": {"price": 115.00}}
{"delete": {"_id": "3003"}}

'

Dans cet exemple :

1. Le document 2001 est indexé.
2. Le document 1001 est partiellement mis à jour (le prix est réduit).
3. Le document 3003 est supprimé.

Réponse en masse (Bulk Response) : La réponse détaillera le succès ou l'échec de chaque opération individuelle au sein du lot, vous permettant d'identifier les documents qui ont réussi et ceux qui ont échoué.

---

Résumé des commandes API clés

Opération	Méthode HTTP	Modèle de point de terminaison	Effet
Indexation (ID auto)	POST	/{index}/_doc/	Crée un nouveau document avec un ID généré automatiquement.
Indexation/Écrasement	PUT	/{index}/_doc/{id}	Crée ou remplace complètement le document à l'ID spécifié.
Mise à jour partielle	POST	/{index}/_update/{id}	Fusionne les modifications spécifiées dans le bloc doc.
Opérations en masse (Bulk)	POST	/{index}/_bulk	Exécute plusieurs opérations en une seule requête.

La maîtrise de ces interactions fondamentales de l'API REST constitue la base d'une gestion dynamique des données au sein de toute application Elasticsearch.