Elasticsearch e OpenSearch

Come cercare in Query DSL, SQL, ES|QL o PPL, come si sfoglia, cosa mostrano le aggregazioni e «Spiega», e perché la query legge soltanto.

Dove si trova: Workspace › Strumenti › Query

Si applica a: Elasticsearch OpenSearch

La query invia al cluster quello che scrivi, tramite la sessione aperta. Esegui (⌘↩) la esegue e Ferma (⌘.) smette di aspettare la risposta: quello che il server ha già iniziato può comunque finire.

Il linguaggio
Il selettore del linguaggio nella barra mostra solo i linguaggi del prodotto della sessione. Entrambi hanno Query DSL —il corpo JSON di _search— e SQL.

Query DSL
Il corpo va intero a _search degli indici scritti in Indici: vuoto significa tutti, e più indici si separano con virgole. Scegli un indice li elenca. Il menu Pagina: 50 dice quanti documenti porta ogni pagina (50 se non lo cambi), a meno che il corpo non abbia il proprio size, che prevale. Un JSON rotto lo rifiuta il server, e l’errore dice dov’è lo sbaglio: la riga e la colonna, o il byte del corpo.

Le pagine e il totale
Pagina successiva chiede la successiva. Se la ricerca ordina (sort), passa per search_after, che riprende dall’ultimo documento ricevuto e non ha limite. Se non ordina, passa per from, che il server taglia a 10.000 documenti, e la vista lo segnala. Il server smette di contare a 10.000 e il totale compare come «10.000 o più»; Totale esatto gli chiede di contarli tutti (track_total_hits), a costo di tempo.

Cosa si vede
Documenti mostra ogni documento chiuso su una riga, con il suo punteggio; aprilo per vedere tutto il suo _source. Tabella mette i campi in colonne, con gli oggetti annidati appiattiti. Se il corpo ha delle aggs, le Aggregazioni compaiono sotto, ad albero. Spiega, su ogni documento, chiede al server perché corrisponde alla ricerca (_explain) e mostra come ha calcolato il punteggio.

SQL, ES|QL e PPL
In questi linguaggi l’indice va dentro la query (FROM, source=), e la risposta è una tabella. L’intestazione di ogni colonna porta il tipo che dichiara il server, che non sempre coincide tra linguaggi né tra prodotti. Se la licenza del cluster non include un linguaggio, lo dice il server; la licenza base di Elasticsearch include SQL e ES|QL.

Legge soltanto
La query non scrive: il corpo Query DSL va sempre a _search, SQL, ES|QL e PPL interrogano soltanto, e un DELETE scritto in SQL non viene inviato. Qui non c’è cancellazione né aggiornamento per query (_delete_by_query, _update_by_query).

Parole chiave: elasticsearch, opensearch, query, ricerca, query dsl, _search, sql, es|ql, esql, ppl, search_after, from, totale, aggregazioni, spiega, _explain, traduci

Cosa mostra ogni scheda di un indice, cosa si può scrivere e come, dove finisce il log delle lente e perché non c’è la reindicizzazione.

Dove si trova: Workspace › Strumenti › Indici

Si applica a: Elasticsearch OpenSearch

La scheda ha tre sezioni, nel selettore della barra: Indici, Modelli e Pipeline. Ricarica rilegge quella mostrata.

Indici
A sinistra, gli indici del cluster con il loro stato —un simbolo e il suo nome, mai solo un colore—, i documenti e la dimensione. Gli indici di sistema (quelli che iniziano con un punto e quelli che il server nasconde) sono compressi nel loro gruppo. Il numero di documenti dell’elenco è quello di Lucene, che conta a parte ogni oggetto di un campo nested; quelli che restituisce una ricerca sono in Statistiche. Scegli un indice e a destra compare il suo dettaglio, in schede che si leggono quando le apri:

- Campi: il mapping come albero, ogni campo con tipo, parametri e sottocampi.
- Impostazioni: le impostazioni scritte sull’indice (non quelle predefinite), con la soglia delle lente in testa.
- Shard: ogni shard, primario o replica, con stato, nodo e, se non ha nodo, il motivo.
- Alias: gli alias che puntano all’indice.
- Documenti: un campione dei documenti, 25 alla volta.
- Statistiche: i documenti di primo livello accanto a quelli di Lucene, la dimensione e i contatori di attività, che sommano da quando l’indice è stato aperto sul suo nodo.

I documenti
Il campione segue l’ordine in cui l’indice li conserva e dice il totale esatto. Scorre solo i primi 10.000 (index.max_result_window): oltre lo dice lo schermo, e per scorrere un indice intero c’è la Query, che pagina con search_after.

Cosa si scrive
Nuovo indice…, nella barra, apre il JSON di un nuovo indice, con uno shard, senza repliche e il mapping vuoto. Elimina indice…, nel dettaglio, chiede conferma nominando l’indice e quanti documenti ha; su un indice di sistema non compare. In Documenti, Nuovo documento… crea un documento con l’_id che scrivi —se esiste già, il server lo rifiuta e non lo sostituisce— o con uno del server se lo lasci vuoto. Modifica documento… sostituisce il documento intero: un campo tolto nel foglio scompare. E solo se nessuno l’ha cambiato da quando l’hai letto; altrimenti il server rifiuta e non sovrascrive l’altra modifica. Elimina documento… chiede conferma nominando il suo _id. Tutto passa per la protezione della connessione, e con l’etichetta di sola lettura niente di questo compare.

Il log delle lente
Modifica soglia delle lente…, in Impostazioni, fissa da quanto tempo in su una ricerca lenta viene scritta nel log: la fase di query e quella di recupero, ognuna per avviso e info. Scrivi un tempo con la sua unità (500ms, 2s); -1 la disattiva, e vuota torna a quella predefinita, che non registra nulla.

Il log non lo conserva Calíope: lo scrive il server. In un’installazione da pacchetto va nella sua cartella dei log (path.logs), in un file <cluster>_index_search_slowlog; in un container, nell’output del container (docker logs).

Modelli e Pipeline
Sono del cluster, non di un indice, e si leggono soltanto. Ogni riga riassume il modello (i suoi pattern, la sua priorità e da quali modelli è composto) o la pipeline (la sua descrizione e quanti processori ha); aprila per vedere il suo JSON intero. Anche i modelli vecchi (_template) compaiono, segnati come tali. Quelli che il server dichiara suoi e quelli che iniziano con un punto sono compressi nel loro gruppo. Calíope non li modifica: si cambiano tramite l’API.

Cosa non fa
Non c’è reindicizzazione (_reindex) né cambio di tipo di un campo esistente: il server non cambia il tipo di un campo che ha già dati, e copiare un indice in un altro è un lungo lavoro del server che si avvia tramite l’API.

Parole chiave: elasticsearch, opensearch, indici, indice, mapping, impostazioni, shard, alias, documenti, statistiche, lente, slowlog, modelli, _index_template, pipeline, ingestione, max_result_window

Che cosa vogliono dire verde, giallo e rosso, come si contano i nodi, che cosa sono i ruoli e come leggere perché uno shard non ha nodo.

Dove si trova: Workspace › Strumenti › Cluster

Si applica a: Elasticsearch OpenSearch

La scheda legge il cluster all’apertura e con Aggiorna; non si aggiorna da sola, perché il cluster non avvisa dei suoi cambiamenti.

La salute
In alto c’è la salute con il suo glifo e il suo nome, mai solo un colore:

- green: tutti gli shard, primari e repliche, hanno un nodo.
- yellow: tutti i primari hanno un nodo, ma qualche replica no. I dati si leggono e si scrivono per intero; manca la copia che darebbe la replica se un nodo cadesse.
- red: qualche primario non ha nodo, e i documenti di quello shard non si possono né leggere né scrivere.

Sotto, quanti nodi rispondono tra quelli che il cluster si aspetta. Il conto viene dai nodi che la sessione ha visto e dalla configurazione di voto del cluster, quindi anche un nodo caduto prima della connessione viene contato: si nomina con il suo identificativo, perché nessuno ne dice il nome. Poi il master (_cat/master) e gli shard: attivi, in spostamento, in inizializzazione e non assegnati. Quando un nodo cade, le sue repliche aspettano un minuto che torni (index.unassigned.node_left.delayed_timeout) prima di essere copiate altrove, e la cifra lo dice tra parentesi.

Nodi
Una riga per nodo con ruoli, heap, RAM, CPU, carico, disco, shard e versione. Ruoli contiene le lettere di node.role: m master, d dati, i ingest, r client remoto; le altre sono livelli di dati. Con il puntatore sopra si leggono per intero.

Shard con problemi
Gli shard non attivi: prima i non assegnati, i primari prima delle repliche e gli indici dell’utente prima di quelli di sistema. Il primo non assegnato si spiega con POST /_cluster/allocation/explain: Motivo (per esempio NODE_LEFT, il nodo se n’è andato), Si può assegnare? e che cosa decide ogni nodo. Spiegazione del server è il testo del server così com’è, in inglese. Un caso frequente: con due nodi, un indice con due repliche non ha posto per la seconda, perché un nodo non tiene due copie dello stesso shard (same_shard), e il cluster resta giallo finché non torna il terzo.

Attività del cluster in coda e Recuperi in corso
Le attività del cluster che aspettano il loro turno (_cat/pending_tasks) e le copie di shard in corso (_cat/recovery).

Se una parte non si è potuta leggere, porta il suo avviso e le altre si mostrano lo stesso. La scheda legge soltanto: non riassegna shard né cambia le impostazioni del cluster.

Parole chiave: elasticsearch, opensearch, cluster, salute, green, yellow, red, verde, giallo, rosso, nodi, master, shard, non assegnati, unassigned, allocation explain, repliche, ruoli, node.role, attività in coda, recuperi

Che cosa misura ogni scheda, perché l’avviso dell’heap parte dal 75 %, perché le velocità sono differenze tra due letture e che cosa vuol dire un rifiuto in un thread pool.

Dove si trova: Workspace › Strumenti › Nodo

Si applica a: Elasticsearch OpenSearch

La scheda legge il nodo all’apertura e, finché è in primo piano, ogni 5 s; cambiando scheda la lettura si ferma. Mentre si legge da sola, Attività la mostra come «Nodo di ricerca, ogni 5 s». Aggiorna la legge subito.

Nodo
Per impostazione predefinita è il nodo che risponde alla sessione. Se il cluster ne ha più di uno, il selettore permette di sceglierne un altro.

Le schede
- Heap della JVM: l’occupato sul massimo. Dal 75 % porta un avviso con glifo e testo: è la soglia alla quale Elastic consiglia di esaminare la pressione di memoria, perché oltre la JVM passa più tempo a raccogliere e i circuit breaker, che interrompono una richiesta prima che il nodo resti senza memoria, sono più vicini a scattare.
- Garbage collection: quelle della generazione giovane e quelle della vecchia, con il tempo impiegato; vecchie che crescono in fretta sono il segno di un heap che non ce la fa.
- CPU: quella della macchina e, sotto, quella del processo del nodo.
- Disco: l’occupato è il totale meno il disponibile. Dall’85 % porta un avviso: è la soglia bassa del disco del cluster (cluster.routing.allocation.disk.watermark.low), e oltre il cluster smette di assegnare repliche a quel nodo.
- Query al secondo e Documenti indicizzati al secondo: la prima con la latenza media delle query dell’intervallo.

Le velocità sono differenze
Il server dà solo contatori accumulati dall’avvio del nodo. Una velocità è la differenza tra due letture divisa per il tempo trascorso tra loro secondo l’orologio del nodo, quindi la prima lettura dice «Serve una seconda lettura» e la cifra arriva con la successiva. Sotto c’è il totale dall’avvio.

Thread pool
Ogni pool con i suoi thread, gli attivi, la coda, i rifiutati e i completati. Quando la coda di un pool è piena, il nodo rifiuta la richiesta successiva con un 429 invece di aspettare. I pool con rifiuti sono evidenziati da un glifo e quelli inattivi sono ripiegati. Rifiuti e completati si contano dall’avvio: una cifra alta può essere vecchia, e ciò che conta è se cresce tra una lettura e l’altra.

Scheda del nodo
La versione, i ruoli, l’indirizzo, il sistema operativo, i processori, la JVM, l’heap massimo, i percorsi e i plugin.

Thread caldi
Con Leggi i thread caldi il nodo campiona per mezzo secondo e restituisce i tre thread che hanno usato più CPU. È il testo del server così com’è, in inglese; con il nodo inattivo porta solo l’intestazione.

La scheda legge soltanto: non cambia le impostazioni del nodo.

Parole chiave: elasticsearch, opensearch, nodo, jvm, heap, gc, garbage collection, cpu, disco, watermark, query al secondo, indicizzazione, thread pool, rifiuti, rejected, 429, hot threads, plugin

Che cosa mostra l’albero delle attività, ogni quanto viene riletto, quali attività si possono annullare e che cosa risponde il server.

Dove si trova: Workspace › Strumenti › Attività

Si applica a: Elasticsearch OpenSearch

La scheda legge le attività del cluster (GET /_tasks?detailed=true&group_by=parents) all’apertura e, finché è in primo piano, ogni 3 s; cambiando scheda smette di leggere. Mentre legge da sola, Attività lo mostra come «Attività di ricerca, ogni 3 s». Aggiorna le legge subito.

L’albero
Ogni attività madre porta sotto le sue figlie, ordinate per quanto tempo girano. Ogni riga dà l’azione, la descrizione, il nodo per nome (o il suo id se il nome non è noto) e da quanto gira. In un delete by query, un update by query o un reindex dice anche quanti documenti ha fatto su quanti.

Il filtro
Corrisponde all’azione o alla descrizione, senza distinguere le maiuscole, e una madre resta se una delle sue figlie corrisponde.

Ciò che non viene offerto da annullare
- Chiedere l’elenco è anch’essa un’attività del server: è segnata «questo elenco».
- Le persistenti («persistente, del cluster») il server le segna annullabili, ma appartengono al cluster stesso e non vengono offerte.
- Quelle che il server non segna annullabili, quelle di cui l’annullamento è già stato chiesto e, su una connessione di sola lettura, tutte.

Annulla attività
Prima si conferma: l’avviso nomina l’azione, la descrizione e il nodo, e Lasciarla correre la lascia proseguire. Annullare chiede al server di fermarla appena può; ciò che ha già fatto non viene disfatto. Il server risponde sempre con successo e lo schermo dice che cosa è successo: che l’ha segnata annullata, che l’attività era già finita o che il suo nodo non è più nel cluster.

Parole chiave: elasticsearch, opensearch, attività, tasks, _tasks, annullare, cancel, delete_by_query, update_by_query, reindex, persistenti, nodo, avanzamento

Cosa mostra la scheda di un repository e dei suoi snapshot, come se ne crea uno, come lo si segue fino alla fine e come si ripristina a mano.

Dove si trova: Workspace › Strumenti › Snapshot

Si applica a: Elasticsearch OpenSearch

La scheda legge i repository di snapshot del server (GET /_snapshot) e, di quello scelto, i suoi snapshot (GET /_snapshot/<repository>/_all).

Repository
Se il server ne ha più d’uno, lo si sceglie nella barra. Sotto vanno il suo tipo e le sue impostazioni; un’impostazione che nomina una credenziale viene nascosta (••••). Senza alcun repository lo schermo lo dice: un repository si registra sul server (PUT /_snapshot/<nome>), e uno di tipo fs ha bisogno che la sua cartella sia in path.repo di ogni nodo, nella configurazione del server. Calíope non registra repository.

Gli snapshot
Vanno dal più recente al più vecchio. Ognuno dice il suo stato con glifo e parole («Completo», «In corso», «Parziale: qualche shard non è riuscito», «Non riuscito»), quando è iniziato, quanto è durato, i suoi shard e i suoi indici, e l’errore di ogni shard non riuscito.

Crea snapshot
Apre un foglio con il nome e gli indici. Il nome proposto porta la data e l’ora (snapshot-AAAA.MM.GG-HHMMSS); va in minuscolo e senza spazi, altrimenti il server lo rifiuta e il foglio ne mostra il motivo. Gli indici vanno separati da virgole e ammettono caratteri jolly; vuoto significa tutti quelli del cluster. Un indice che non esiste viene saltato, e lo stato globale (modelli e impostazioni del cluster) non entra. Creare passa per la protezione di scrittura della connessione: su una in sola lettura il pulsante non compare.

Il foglio si chiude appena il server accetta la richiesta, e Attività segue lo snapshot come «Snapshot di ricerca», con gli shard completati come avanzamento. Non ha «Ferma»: fermarlo lo lascerebbe a metà. La fine la conferma l’elenco degli snapshot, perché OpenSearch impiega un istante a darlo per terminato. Se dopo dieci minuti è ancora in corso, lo schermo lo dice e Aggiorna mostra poi come è finito.

Il ripristino non è offerto
Ripristinare sovrascrive indici aperti e si decide fuori da uno strumento di interrogazione. Il piede dell’elenco lo dice e scrive la richiesta per farlo a mano: POST /_snapshot/<repository>/<nome>/_restore.

Parole chiave: elasticsearch, opensearch, snapshot, _snapshot, repository, path.repo, creare, ripristinare, restore, shard, backup