La Guida Definitiva alla Gestione degli Indici Elasticsearch tramite Comandi API

Gestire gli indici Elasticsearch tramite API è un lavoro ordinario, ma è anche dove accadono molti errori costosi. Un mapping sbagliato può forzare un reindicizzazione. Un'eliminazione con wildcard può rimuovere più di quanto intendessi. Un'impostazione di replica che aveva senso in sviluppo può lasciare la produzione in stato giallo dopo un deployment.

Un indice Elasticsearch non è solo un bucket di documenti JSON. Ha mapping, impostazioni, alias, conteggi di shard, conteggi di replica, analizzatori e comportamento del ciclo di vita. Non è necessario memorizzare ogni API per gestirlo bene, ma è necessario un approccio attento: creare indici intenzionalmente, ispezionare ciò che Elasticsearch ha effettivamente creato, aggiornare solo le impostazioni che possono essere modificate in sicurezza ed eliminare con protezioni.

Gli esempi seguenti utilizzano richieste in stile Kibana Dev Tools. Se preferisci curl, gli stessi percorsi e corpi JSON si applicano a http://host:9200.

Cosa contiene un indice

Un indice è uno spazio dei nomi logico per i documenti. Sotto il cofano, gli shard primari contengono i dati e gli shard di replica copiano quei dati per ridondanza e capacità di ricerca. Il comportamento predefinito esatto di shard e replica può variare in base alla versione di Elasticsearch e alla modalità di deployment, quindi non fare affidamento sulla memoria. Controlla le impostazioni nel tuo cluster.

I tre elementi che ispezionerai più spesso sono:

• settings, come number_of_shards, number_of_replicas, refresh_interval e la configurazione dell'analisi.
• mappings, che definiscono i tipi di campo come keyword, text, date, long, double, boolean, ip e campi nested/object.
• aliases, che consentono alle applicazioni di utilizzare un nome stabile mentre scambi l'indice fisico sottostante.

Un buon flusso di lavoro API per gli indici inizia prima che il primo documento venga indicizzato. Il mapping dinamico è utile per l'esplorazione, ma gli indici di produzione meritano mapping espliciti per i campi importanti. Se user_id viene accidentalmente mappato come text, le aggregazioni e i filtri esatti diventano problematici. Se un timestamp viene mappato come text, le query su intervalli di tempo non si comporteranno come query su date. Questi errori sono risolvibili, ma di solito creando un nuovo indice e reindicizzando.

Creare un indice semplice

La richiesta di creazione più piccola è:

PUT /my_first_index

Elasticsearch restituisce un acknowledgement se l'indice è stato creato:

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

Va bene per un indice di prova. Per dati reali, crea l'indice con le impostazioni e i mapping che ti aspetti, piuttosto che lasciare che i primi documenti ne definiscano la forma.

Creare un indice con mapping e impostazioni

Ecco un indice products pratico. Supporta la ricerca full-text su nomi e descrizioni, il filtraggio esatto su ID e categorie, l'ordinamento per data, i filtri su intervalli numerici e semplici controlli di 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" }
    }
  }
}

Alcune scelte qui sono deliberate. product_id, sku e category sono keyword perché normalmente filtri, aggreghi o unisci il comportamento dell'applicazione attorno a valori esatti. name è text per la ricerca, con un sottocampo keyword name.raw per l'ordinamento e la corrispondenza esatta. price utilizza scaled_float in modo che i prezzi possano essere memorizzati come valori scalati simili a centesimi invece di approssimazioni in virgola mobile binarie. dynamic: strict rifiuta campi sconosciuti, il che è utile quando i dati di un producer errati devono fallire rumorosamente.

Non copiare ciecamente il conteggio degli shard. Tre shard primari potrebbero essere troppi per un piccolo indice e troppo pochi per uno grande. Il conteggio degli shard è difficile da modificare dopo la creazione senza una migrazione di tipo shrink, split o reindex, quindi dimensiona in base al volume di dati previsto, alla conservazione e al numero di nodi.

Ispezionare un indice dopo la creazione

Verifica sempre cosa ha accettato Elasticsearch:

GET /products-v1

Restituisce impostazioni, mapping e alias. Per controlli mirati, usa endpoint più specifici:

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

Per una vista compatta da riga di comando di molti indici:

GET /_cat/indices/products-*?v

Le colonne utili includono health, status, conteggio shard primari, conteggio repliche, conteggio documenti, conteggio documenti eliminati e dimensione dello store. Le API _cat sono pensate per gli umani. Usa le API JSON per gli script.

Se stai controllando se un campo è mappato correttamente, usa:

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

È più veloce da leggere che scorrere un mapping grande.

Aggiornare le impostazioni dell'indice in sicurezza

Alcune impostazioni sono dinamiche. Il conteggio delle repliche è quello comune:

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

Questo può trasformare un cluster verde in giallo se non hai abbastanza nodi dati adatti. Ad esempio, un primario più due repliche necessita di tre posti separati per posizionare le copie. Le regole di allocation awareness possono rendere il requisito più restrittivo.

refresh_interval è un'altra impostazione che potresti modificare durante i caricamenti bulk:

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

Un intervallo di refresh più lungo può ridurre il sovraccarico di indicizzazione, ma i documenti appena indicizzati diventano visibili alla ricerca meno rapidamente. Per un backfill bulk, i team spesso aumentano o disabilitano temporaneamente i refresh, caricano i dati, quindi ripristinano l'intervallo normale e fanno un refresh una volta:

POST /products-v1/_refresh

Alcune impostazioni sono statiche. number_of_shards non può essere modificato su un indice esistente aperto. Se scopri che il conteggio degli shard primari è sbagliato, pianifica un nuovo indice e una migrazione.

Modificare i mapping senza ingannare te stesso

Puoi aggiungere nuovi campi a un mapping:

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

Generalmente non puoi cambiare il tipo di un campo esistente sul posto. Se price è già text, questo non trasformerà i vecchi valori in un campo numerico utile. Crea un nuovo indice con il mapping corretto e reindicizza:

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

Per le migrazioni in produzione, usa gli alias in modo che l'applicazione non debba conoscere la versione fisica dell'indice.

Usare gli alias per un accesso applicativo più sicuro

Punta un alias alla prima versione:

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

La tua applicazione legge da products. Successivamente, crea products-v2, reindicizza i dati, testali, quindi scambia l'alias atomicamente:

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

Per sistemi con molte scritture, usa un alias di scrittura e sii esplicito su is_write_index:

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

Gli alias sono uno dei modi più semplici per evitare di hardcodare le versioni degli indici nei servizi.

Elencare e cercare i nomi degli indici con attenzione

Per ispezionare più indici:

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

Fai attenzione con wildcard ampi su cluster grandi. GET /* o GET /_all possono produrre una risposta enorme e possono includere indici di sistema o nascosti a seconda della versione, delle impostazioni e delle opzioni di richiesta. Preferisci un pattern ristretto come logs-prod-* o products-*.

Per verificare se un indice esiste da uno script, usa HEAD:

HEAD /products-v1

Un 200 significa che esiste. Un 404 significa che non esiste.

Eliminare gli indici con protezioni

Eliminare è semplice:

DELETE /products-v1

Il rischio operativo non è la sintassi. Il rischio è eliminare l'indice sbagliato o eliminare prima che uno snapshot sia completato.

Prima di eliminare, elenca esattamente cosa corrisponde al pattern:

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

Se l'output è corretto e i dati sono recuperabili o non più necessari, elimina lo stesso pattern:

DELETE /products-old-*

Molti cluster limitano le operazioni distruttive con wildcard usando action.destructive_requires_name. Questa è una buona impostazione di sicurezza perché blocca eliminazioni ampie come DELETE /* a meno che non siano richiesti nomi espliciti. Anche con quella protezione, tratta le operazioni di eliminazione come cambiamenti di produzione: conferma il pattern dell'indice, conferma gli snapshot e conferma che il chiamante abbia i permessi giusti.

Preferire le policy del ciclo di vita per i dati time-series

Le eliminazioni manuali sono accettabili per pulizie una tantum. Per log, metriche, trace e altri dati time-series, usa Index Lifecycle Management o data stream dove appropriato. Una policy del ciclo di vita può fare il rollover di un indice quando raggiunge un obiettivo di età o dimensione, spostare i dati più vecchi a un livello diverso ed eliminarli dopo la scadenza della conservazione.

Questo è importante perché la pulizia manuale tende a fallire nel momento peggiore. Qualcuno se ne dimentica, il disco si riempie, i watermark di flood-stage rendono gli indici di sola lettura, e poi il team sta pulendo sotto pressione. Le policy del ciclo di vita trasformano la conservazione in configurazione invece che in un promemoria sul calendario.

Una semplice routine quotidiana

Per un cluster di produzione, una routine pratica di gestione degli indici si presenta così:

Controlla la salute:

GET /_cluster/health

Elenca gli indici per pattern:

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

Ispeziona impostazioni sospette:

GET /logs-prod-2026.05.24/_settings

Controlla i mapping prima di aggiungere nuovi campi da un rilascio applicativo:

GET /logs-prod-2026.05.24/_mapping

Conferma gli alias prima e dopo una migrazione:

GET /_cat/aliases/products*?v

Non è un lavoro affascinante, ma coglie molti problemi in anticipo: conteggi di replica errati, campi dinamici accidentali, alias obsoleti e vecchi indici che avrebbero dovuto essere eliminati.

Errori comuni da evitare

Non lasciare che le impostazioni predefinite di sviluppo diventino l'architettura di produzione. Un cluster a nodo singolo, zero repliche e mapping dinamici possono andare bene per una demo. Non sono un piano di ripristino.

Non modificare i mapping nella tua testa e presumere che Elasticsearch sia d'accordo. Ispeziona il mapping effettivo.

Non usare eliminazioni con wildcard senza prima elencare gli indici corrispondenti.

Non impostare conteggi di replica elevati senza abbastanza nodi dati e zone per posizionarli.

Non saltare gli alias per gli indici da cui dipendono le applicazioni. La prima migrazione sarà molto più semplice se l'applicazione parla già a un alias.

Una buona gestione degli indici è principalmente ripetizione disciplinata. Crea con intenzione, ispeziona ciò che esiste, migra con alias, automatizza la conservazione e rendi le azioni distruttive noiosamente esplicite.

I template contano più delle creazioni una tantum

Se crei lo stesso tipo di indice ripetutamente, non fare affidamento su chiamate manuali PUT /nome-indice. Usa un index template o template componibili in modo che i nuovi indici ricevano automaticamente i mapping, le impostazioni, gli alias e la policy del ciclo di vita corretti.

Una piattaforma di log è l'esempio classico. Se logs-web-2026.05.24 ha un mapping corretto per @timestamp ma l'indice di domani viene creato dinamicamente dal primo documento, un evento malformato può mappare un campo in modo errato. L'errore potrebbe non manifestarsi fino a quando i dashboard non falliscono o le aggregazioni scompaiono. I template prevengono questa deriva.

Un template semplice potrebbe definire un pattern, impostazioni e mapping per indici futuri:

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" }
      }
    }
  }
}

I template sono anche più facili da revisionare nel codice. Mettili nel version control, distribuiscili attraverso lo stesso percorso delle modifiche applicative e testali prima che il rollover crei il prossimo indice sottostante.

Reindicizzare senza sorprendere l'applicazione

La migrazione di indici più pulita è di solito: crea un nuovo indice versionato, reindicizza i dati, confronta i conteggi e le query di esempio, poi scambia un alias. Non puntare l'applicazione direttamente a products-v1 a meno che non ti piacciano le modifiche di configurazione di emergenza.

Una migrazione attenta si presenta così:

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

Poi reindicizza:

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

Usando wait_for_completion=false restituisce un ID attività in modo da poter monitorare una reindicizzazione lunga. Dopo che è terminata, confronta i conteggi dei documenti ed esegui ricerche rappresentative. Solo allora scambia gli alias.

Per indici con molte scritture, pensa a scritture duali, finestre di pausa o replay da una fonte di verità. I comandi API sono facili; il piano di coerenza è il vero lavoro.

Sicurezza e permessi

Le API degli indici non dovrebbero essere disponibili a ogni utente dell'applicazione. Un servizio di ricerca potrebbe aver bisogno di privilegi di lettura su un alias. Un data ingester potrebbe aver bisogno di privilegi di creazione, indicizzazione e scrittura su un alias di scrittura. Molto poche identità dovrebbero avere ampi privilegi di eliminazione o gestione.

Questo è importante perché le API degli indici sono potenti. Una credenziale applicativa compromessa con privilegi manage può modificare le impostazioni di replica, chiudere indici o eliminare dati. Mantieni i privilegi distruttivi separati e fai in modo che l'eliminazione in produzione richieda un flusso di lavoro operatore piuttosto che un percorso applicativo.

Le convenzioni di denominazione riducono gli errori

Usa nomi che codificano scopo e ciclo di vita: products-v3, logs-web-2026.05.24, metrics-api-000123 o nomi di data stream che corrispondono alla fonte dei dati. Evita nomi vaghi come newindex, test2 o prod-final. Durante la pulizia, i nomi vaghi rendono difficile sapere cosa è sicuro eliminare.

Per gli indici time-series, usa formati di data coerenti ed evita di mescolare ora locale e ipotesi UTC. Per gli indici aziendali versionati, mantieni l'alias stabile e lascia che la versione fisica dell'indice cambi dietro di esso. Una noiosa convenzione di denominazione è una caratteristica di sicurezza operativa.