Elasticsearch et OpenSearch

Comment chercher en Query DSL, SQL, ES|QL ou PPL, comment on pagine, ce que montrent les agrégations et « expliquer », et pourquoi la requête ne fait que lire.

Où le trouver : Espace de travail › Outils › Requête

S'applique à : Elasticsearch OpenSearch

La requête envoie au cluster ce que vous tapez, par la session ouverte. Exécuter (⌘↩) l’exécute et Arrêter (⌘.) cesse d’attendre la réponse : ce que le serveur a déjà commencé peut se terminer quand même.

Le langage
Le sélecteur de langage de la barre ne montre que les langages du produit de la session. Les deux ont Query DSL —le corps JSON de _search— et SQL.

Query DSL
Le corps part entier vers _search des index écrits dans Index : vide, ce sont tous les index, et plusieurs se séparent par des virgules. Choisir un index les liste. Le menu Page : 50 dit combien de documents apporte chaque page (50 si vous n’y touchez pas), sauf si le corps porte son propre size, qui l’emporte. Un JSON cassé est refusé par le serveur, et l’erreur dit où est la faute : la ligne et la colonne, ou l’octet du corps.

Les pages et le total
Page suivante demande la suivante. Si la recherche trie (sort), elle passe par search_after, qui reprend après le dernier document reçu et n’a pas de limite. Si elle ne trie pas, elle passe par from, que le serveur coupe à 10 000 documents, et la vue le signale. Le serveur cesse de compter à 10 000 et le total s’affiche « 10 000 ou plus » ; Total exact lui demande de tout compter (track_total_hits), au prix du temps.

Ce qu’on voit
Documents montre chaque document replié sur une ligne, avec son score ; ouvrez-le pour voir tout son _source. Tableau met les champs en colonnes, avec les objets imbriqués aplatis. Si le corps porte des aggs, les Agrégations apparaissent dessous, en arbre. Expliquer, sur chaque document, demande au serveur pourquoi il correspond à la recherche (_explain) et montre comment il a calculé son score.

SQL, ES|QL et PPL
Dans ces langages l’index va dans la requête (FROM, source=), et la réponse est un tableau. L’en-tête de chaque colonne porte le type que déclare le serveur, qui ne coïncide pas toujours entre langages ni entre produits. Si la licence du cluster n’inclut pas un langage, le serveur le dit ; la licence basique d’Elasticsearch inclut SQL et ES|QL.

Elle ne fait que lire
La requête n’écrit pas : le corps Query DSL part toujours vers _search, SQL, ES|QL et PPL ne font qu’interroger, et un DELETE écrit en SQL n’est pas envoyé. Il n’y a ici ni suppression ni mise à jour par requête (_delete_by_query, _update_by_query).

Mots-clés : elasticsearch, opensearch, requête, recherche, query dsl, _search, sql, es|ql, esql, ppl, search_after, from, total, agrégations, expliquer, _explain, traduire

Ce que montre chaque onglet d’un index, ce qu’on peut écrire et comment, où va le journal des lentes et pourquoi il n’y a pas de réindexation.

Où le trouver : Espace de travail › Outils › Index

S'applique à : Elasticsearch OpenSearch

L’onglet a trois sections, dans le sélecteur de la barre : Index, Modèles et Pipelines. Recharger relit celle qui est affichée.

Index
À gauche, les index du cluster avec leur santé —un symbole et son nom, jamais seulement une couleur—, leurs documents et leur taille. Les index système (ceux qui commencent par un point et ceux que le serveur masque) sont repliés dans leur groupe. Le nombre de documents de la liste est celui de Lucene, qui compte à part chaque objet d’un champ nested ; ce que renvoie une recherche est dans Statistiques. Choisissez un index et son détail apparaît à droite, dans des onglets lus à leur ouverture :

- Champs : le mapping en arbre, chaque champ avec son type, ses paramètres et ses sous-champs.
- Réglages : les réglages écrits sur l’index (pas ceux par défaut), avec le seuil des lentes en premier.
- Shards : chaque shard, primaire ou réplique, avec son état, son nœud et, s’il n’a pas de nœud, le motif.
- Alias : les alias qui pointent vers l’index.
- Documents : un échantillon des documents, 25 par 25.
- Statistiques : les documents de premier niveau à côté de ceux de Lucene, la taille et les compteurs d’activité, cumulés depuis l’ouverture de l’index sur son nœud.

Les documents
L’échantillon suit l’ordre dans lequel l’index les stocke et donne le total exact. Il ne parcourt que les 10 000 premiers (index.max_result_window) : au-delà l’écran le dit, et pour parcourir un index entier il y a la Requête, qui pagine avec search_after.

Ce qui s’écrit
Nouvel index…, dans la barre, ouvre le JSON d’un nouvel index, avec un shard, sans répliques et le mapping vide. Supprimer l’index…, dans le détail, demande confirmation en nommant l’index et son nombre de documents ; il n’apparaît pas sur un index système. Dans Documents, Nouveau document… crée un document avec l’_id que vous saisissez —s’il existe déjà, le serveur le refuse et ne le remplace pas— ou avec un identifiant du serveur si vous le laissez vide. Modifier le document… remplace le document entier : un champ retiré dans la fiche disparaît. Et seulement si personne ne l’a modifié depuis votre lecture ; sinon le serveur refuse et n’écrase pas l’autre modification. Supprimer le document… demande confirmation en nommant son _id. Tout passe par la protection de la connexion, et avec l’étiquette de lecture seule rien de cela n’apparaît.

Le journal des lentes
Modifier le seuil des lentes…, dans Réglages, fixe à partir de quelle durée une recherche lente est écrite dans le journal : la phase de requête et celle de récupération, chacune en avertissement et en info. Saisissez une durée avec son unité (500ms, 2s) ; -1 le désactive, et vide revient à la valeur par défaut, qui n’enregistre rien.

Ce n’est pas Calíope qui garde le journal : c’est le serveur qui l’écrit. Dans une installation par paquet, il va dans son répertoire de journaux (path.logs), dans un fichier <cluster>_index_search_slowlog ; dans un conteneur, dans la sortie du conteneur (docker logs).

Modèles et Pipelines
Ils appartiennent au cluster, pas à un index, et sont en lecture seule. Chaque ligne résume le modèle (ses motifs, sa priorité et les modèles qui le composent) ou le pipeline (sa description et son nombre de processeurs) ; ouvrez-la pour voir son JSON entier. Les anciens modèles (_template) apparaissent aussi, marqués comme tels. Ceux que le serveur déclare siens et ceux qui commencent par un point sont repliés dans leur groupe. Calíope ne les modifie pas : ils se changent par l’API.

Ce qu’il ne fait pas
Il n’y a pas de réindexation (_reindex) ni de changement de type d’un champ existant : le serveur ne change pas le type d’un champ qui contient déjà des données, et copier un index dans un autre est une longue tâche du serveur lancée par l’API.

Mots-clés : elasticsearch, opensearch, index, mapping, réglages, shards, alias, documents, statistiques, lentes, slowlog, modèles, _index_template, pipelines, ingestion, max_result_window

Ce que veulent dire vert, jaune et rouge, comment les nœuds sont comptés, ce que sont les rôles et comment lire pourquoi un shard n’a pas de nœud.

Où le trouver : Espace de travail › Outils › Cluster

S'applique à : Elasticsearch OpenSearch

L’onglet lit le cluster à l’ouverture et avec Actualiser ; il ne se rafraîchit pas seul, car le cluster ne signale pas ses changements.

La santé
En haut, la santé avec son symbole et son nom, jamais seulement une couleur :

- green : tous les shards, primaires et répliques, ont un nœud.
- yellow : tous les primaires ont un nœud, mais une réplique n’en a pas. Les données se lisent et s’écrivent en entier ; ce qui manque, c’est la copie que donnerait la réplique si un nœud tombait.
- red : un primaire n’a pas de nœud, et les documents de ce shard ne peuvent être ni lus ni écrits.

En dessous, combien de nœuds répondent sur ceux que le cluster attend. Le compte vient des nœuds que la session a vus et de la configuration de vote du cluster, donc un nœud tombé avant la connexion est compté lui aussi : il est nommé par son identifiant, car personne ne donne son nom. Puis le master (_cat/master) et les shards : actifs, en déplacement, en initialisation et non assignés. Quand un nœud tombe, ses répliques attendent une minute qu’il revienne (index.unassigned.node_left.delayed_timeout) avant d’être copiées ailleurs, et le chiffre le dit entre parenthèses.

Nœuds
Une ligne par nœud avec ses rôles, heap, RAM, CPU, charge, disque, shards et version. Rôles porte les lettres de node.role : m master, d données, i ingestion, r client distant ; les autres sont des niveaux de données. Avec le pointeur dessus, on les lit en entier.

Shards à problème
Les shards qui ne sont pas actifs : d’abord les non assignés, les primaires avant les répliques et les index de l’utilisateur avant ceux du système. Le premier non assigné est expliqué avec POST /_cluster/allocation/explain : Motif (par exemple NODE_LEFT, le nœud est parti), Peut-il être assigné ? et ce que décide chaque nœud. Explication du serveur est le texte du serveur tel quel, en anglais. Un cas fréquent : avec deux nœuds, un index à deux répliques n’a pas de place pour la seconde, car un nœud ne garde pas deux copies du même shard (same_shard), et le cluster reste jaune jusqu’au retour du troisième.

Tâches du cluster en attente et Récupérations en cours
Les tâches du cluster qui attendent leur tour (_cat/pending_tasks) et les copies de shards en cours (_cat/recovery).

Si une partie n’a pas pu être lue, elle porte son avertissement et les autres s’affichent quand même. L’onglet ne fait que lire : il ne réassigne pas de shards et ne change pas les réglages du cluster.

Mots-clés : elasticsearch, opensearch, cluster, santé, green, yellow, red, vert, jaune, rouge, nœuds, master, shards, non assigné, unassigned, allocation explain, répliques, rôles, node.role, tâches en attente, récupérations

Ce que mesure chaque carte, pourquoi l’avertissement du tas commence à 75 %, pourquoi les débits sont des différences entre deux lectures et ce que veut dire un rejet dans un thread pool.

Où le trouver : Espace de travail › Outils › Nœud

S'applique à : Elasticsearch OpenSearch

L’onglet lit le nœud à l’ouverture et, tant qu’il est devant, toutes les 5 s ; en changeant d’onglet, la lecture s’arrête. Pendant qu’il se lit seul, Activité l’affiche comme « Nœud de recherche, toutes les 5 s ». Actualiser le lit tout de suite.

Nœud
Par défaut, c’est le nœud qui répond à la session. Si le cluster en a plusieurs, le sélecteur permet d’en choisir un autre.

Les cartes
- Tas de la JVM : l’occupé sur le maximum. À partir de 75 % elle porte un avertissement avec glyphe et texte : c’est le seuil auquel Elastic conseille d’examiner la pression mémoire, car au-dessus la JVM passe plus de temps à collecter et les circuit breakers, qui coupent une requête avant que le nœud manque de mémoire, sont plus près de se déclencher.
- Passages du ramasse-miettes : celles de la jeune génération et celles de la vieille, avec le temps qu’elles ont pris ; des vieilles qui croissent vite signalent un tas qui ne suit plus.
- CPU : celui de la machine et, en dessous, celui du processus du nœud.
- Disque : l’occupé est le total moins le disponible. À partir de 85 % elle porte un avertissement : c’est le seuil bas de disque du cluster (cluster.routing.allocation.disk.watermark.low), et au-dessus le cluster cesse d’assigner des répliques à ce nœud.
- Requêtes par seconde et Documents indexés par seconde : la première, avec la latence moyenne des requêtes de l’intervalle.

Les débits sont des différences
Le serveur ne donne que des compteurs cumulés depuis le démarrage du nœud. Un débit est la différence entre deux lectures divisée par le temps écoulé entre elles selon l’horloge du nœud ; la première lecture dit donc « Il faut une deuxième lecture » et le chiffre arrive avec la suivante. En dessous figure le total depuis le démarrage.

Pools de threads
Chaque pool avec ses threads, les actifs, la file, les rejetés et les terminés. Quand la file d’un pool est pleine, le nœud rejette la requête suivante avec un 429 au lieu d’attendre. Les pools avec rejets sont signalés par un glyphe, et ceux sans activité sont repliés. Rejets et terminés se comptent depuis le démarrage : un chiffre élevé peut être ancien, et ce qui compte, c’est s’il augmente entre deux lectures.

Fiche du nœud
La version, les rôles, l’adresse, le système d’exploitation, les processeurs, la JVM, le tas maximal, les chemins et les plugins.

Threads chauds
Avec Lire les threads chauds le nœud échantillonne une demi-seconde et renvoie les trois threads qui ont le plus consommé de CPU. C’est le texte du serveur tel quel, en anglais ; nœud au repos, il n’apporte que l’en-tête.

L’onglet ne fait que lire : il ne modifie pas les réglages du nœud.

Mots-clés : elasticsearch, opensearch, nœud, jvm, tas, heap, gc, ramasse-miettes, cpu, disque, watermark, requêtes par seconde, indexation, thread pool, rejets, rejected, 429, threads chauds, hot threads, plugins

Ce que montre l’arbre des tâches, à quelle fréquence il est relu, quelles tâches peuvent être annulées et ce que répond le serveur.

Où le trouver : Espace de travail › Outils › Tâches

S'applique à : Elasticsearch OpenSearch

L’onglet lit les tâches du cluster (GET /_tasks?detailed=true&group_by=parents) à l’ouverture et, tant qu’il est au premier plan, toutes les 3 s ; changer d’onglet arrête la lecture. Pendant qu’il lit tout seul, Activité l’affiche comme « Tâches de recherche, toutes les 3 s ». Actualiser les lit tout de suite.

L’arbre
Chaque tâche mère porte ses filles en dessous, triées selon le temps qu’elles tournent. Chaque ligne donne l’action, la description, le nœud par son nom (ou son identifiant si le nom est inconnu) et depuis combien de temps elle tourne. Dans un delete by query, un update by query ou un reindex, elle dit aussi combien de documents sont faits sur combien.

Le filtre
Il porte sur l’action ou la description, sans tenir compte de la casse, et une mère reste si l’une de ses filles correspond.

Ce qui n’est pas proposé à l’annulation
- Demander la liste est aussi une tâche du serveur : elle est marquée « cette liste ».
- Les persistantes (« persistante, du cluster ») sont marquées annulables par le serveur, mais elles appartiennent au cluster lui-même et ne sont pas proposées.
- Celles que le serveur ne marque pas annulables, celles dont l’annulation est déjà demandée et, sur une connexion en lecture seule, toutes.

Annuler la tâche
On confirme d’abord : l’alerte nomme l’action, la description et le nœud, et La laisser tourner la laisse continuer. Annuler demande au serveur de l’arrêter dès qu’il peut ; ce qu’elle a déjà fait n’est pas défait. Le serveur répond toujours par un succès et l’écran dit ce qui s’est passé : qu’il l’a marquée annulée, que la tâche était déjà finie ou que son nœud n’est plus dans le cluster.

Mots-clés : elasticsearch, opensearch, tâches, tasks, _tasks, annuler, cancel, delete_by_query, update_by_query, reindex, persistantes, nœud, progression

Ce que l’onglet montre d’un dépôt et de ses instantanés, comment en créer un, comment on le suit jusqu’à la fin et comment restaurer à la main.

Où le trouver : Espace de travail › Outils › Instantanés

S'applique à : Elasticsearch OpenSearch

L’onglet lit les dépôts d’instantanés du serveur (GET /_snapshot) et, pour celui choisi, ses instantanés (GET /_snapshot/<dépôt>/_all).

Dépôt
Si le serveur en a plusieurs, on le choisit dans la barre. En dessous viennent son type et ses réglages ; un réglage qui nomme un identifiant est masqué (••••). Sans aucun dépôt, l’écran le dit : un dépôt s’enregistre sur le serveur (PUT /_snapshot/<nom>), et un dépôt de type fs a besoin que son dossier figure dans path.repo de chaque nœud, dans la configuration du serveur. Calíope n’enregistre pas de dépôts.

Les instantanés
Ils vont du plus récent au plus ancien. Chacun donne son état par un glyphe et en mots (« Complet », « En cours », « Partiel : un shard a échoué », « Échec »), quand il a commencé, combien de temps il a duré, ses shards et ses index, et l’échec de chaque shard en échec.

Créer un instantané
Ouvre une feuille avec le nom et les index. Le nom proposé porte la date et l’heure (snapshot-AAAA.MM.JJ-HHMMSS) ; il doit être en minuscules et sans espaces, sinon le serveur le refuse et la feuille montre son motif. Les index sont séparés par des virgules et acceptent les jokers ; vide, ce sont tous ceux du cluster. Un index qui n’existe pas est ignoré, et l’état global (modèles et réglages du cluster) n’est pas inclus. Créer passe par la garde d’écriture de la connexion : sur une connexion en lecture seule, le bouton n’apparaît pas.

La feuille se ferme dès que le serveur accepte la requête, et Activité suit l’instantané comme « Instantané de recherche », avec les shards faits comme avancement. Il n’a pas de « Arrêter » : arrêter le laisserait à moitié fait. La fin est confirmée par la liste des instantanés, car OpenSearch met un instant à le donner pour terminé. S’il est encore en cours au bout de dix minutes, l’écran le dit et Actualiser montre ensuite comment il s’est terminé.

La restauration n’est pas proposée
Restaurer écrase des index ouverts et se décide hors d’un outil de requête. Le pied de la liste le dit et écrit la requête pour le faire à la main : POST /_snapshot/<dépôt>/<nom>/_restore.

Mots-clés : elasticsearch, opensearch, instantanés, snapshots, _snapshot, dépôt, repository, path.repo, créer, restaurer, restore, shards