Indicizzazione e Aggiornamento dei Documenti con la REST API di Elasticsearch

Elasticsearch è un potente motore di ricerca e analisi distribuito che si basa sull'ingestione di dati ben strutturati. La gestione di questi dati comporta operazioni fondamentali di Creazione, Lettura, Aggiornamento ed Eliminazione (CRUD), eseguite principalmente tramite la sua versatile REST API. Comprendere come indicizzare correttamente nuovi documenti e aggiornare in modo efficiente quelli esistenti è fondamentale per mantenere un archivio dati accurato e in tempo reale.

Questa guida ti accompagnerà attraverso i metodi HTTP essenziali e gli endpoint API utilizzati per indicizzare nuovi record e modificare i documenti esistenti all'interno del tuo cluster Elasticsearch. Ci concentreremo sulla sintassi, sui payload JSON richiesti e sull'interpretazione dei codici di risposta per garantire una gestione dei dati senza interruzioni.

---

Prerequisiti

Prima di procedere, assicurati di avere:

• Un cluster Elasticsearch attivo in esecuzione.
• Uno strumento da riga di comando in grado di effettuare richieste HTTP (come curl) o un client HTTP (come Postman).
• La conoscenza del nome del tuo indice di destinazione.

---

1. Indicizzazione di Nuovi Documenti

L'indicizzazione è il processo di archiviazione di un documento JSON in un indice Elasticsearch. Elasticsearch assegna automaticamente un ID univoco al documento, a meno che non venga fornito esplicitamente uno. Il metodo principale per l'indicizzazione è il metodo HTTP PUT o POST.

1.1 Indicizzazione con ID Automatico (POST)

Quando utilizzi POST sull'endpoint dell'indice, Elasticsearch genera per te un ID di documento univoco. Questo è spesso il metodo preferito per l'ingestione iniziale dei dati quando gli ID sono gestiti internamente.

Endpoint: POST /{index_name}/_doc/

Richiesta di Esempio (utilizzando curl):

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

Frammento di Risposta di Successo:

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

Il campo result che mostra created conferma che un nuovo documento è stato aggiunto.

1.2 Indicizzazione con ID Specifico (PUT)

Se il tuo sistema sorgente fornisce un identificatore univoco per il documento, dovresti usare il metodo PUT che punta a un ID specifico. Se un documento con quell'ID esiste già, PUT sovrascriverà l'intero documento.

Endpoint: PUT /{index_name}/_doc/{document_id}

Richiesta di Esempio: Indicizzazione di un documento con ID 1001.

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

Frammento di Risposta di Successo:

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

Suggerimento sulla Sovrascrittura: Se esegui nuovamente la stessa identica richiesta PUT con lo stesso ID, il result cambierà in updated e il numero _version verrà incrementato.

---

2. Aggiornamento dei Documenti Esistenti

L'aggiornamento dei documenti è diverso dalla sovrascrittura. Quando vuoi modificare solo campi specifici all'interno di un documento esistente senza influenzare i campi non modificati, usi l'endpoint _update, tipicamente con il metodo POST.

2.1 Aggiornamenti Parziali utilizzando _update

L'API _update è cruciale per Aggiornamenti Atomici. Richiede un blocco doc all'interno del payload, che contiene solo i campi che desideri modificare. Elasticsearch recupera il documento, unisce le modifiche e lo reindicizza.

Endpoint: POST /{index_name}/_update/{document_id}

Scenario di Esempio: Vogliamo aggiornare il prezzo del prodotto ID 1001 da $129.99 a $119.99 e contrassegnarlo come non disponibile.

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

Frammento di Risposta di Successo:

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

Nota che _version è incrementato da 1 a 2, riflettendo la modifica.

2.2 Utilizzo di Aggiornamenti tramite Script

Per aggiornamenti più complessi, condizionali o matematici, Elasticsearch supporta lo scripting Painless all'interno dell'API _update. Questo ti consente di eseguire operazioni come l'incremento di contatori o l'impostazione di campi in base ai loro valori correnti.

Scenario di Esempio: Incrementare il conteggio delle scorte di 5 per il documento 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
    }
  }
}
'

Concetto Chiave di Scripting: ctx._source si riferisce alla sorgente del documento corrente.

Avviso sugli Script: Sebbene potenti, script complessi possono influire sulle prestazioni. Usa aggiornamenti di campo semplici (doc) quando possibile, poiché sono generalmente più veloci e sicuri.

---

3. Indicizzazione e Aggiornamenti Bulk

Per operazioni su volumi elevati di dati, inviare richieste individuali per ogni documento è inefficiente. Elasticsearch fornisce l'API _bulk per gestire più operazioni di indicizzazione, aggiornamento o eliminazione in un'unica richiesta.

3.1 Struttura di una Richiesta Bulk

Le richieste bulk utilizzano un formato JSON specifico delimitato da newline (NDJSON). Ogni operazione è definita da una riga di metadati (che specifica l'azione, l'indice e l'ID opzionale) seguita immediatamente dalla sorgente del documento (se richiesta).

Tipi di Azione per Bulk: index, create, update, delete.

Esempio di Richiesta Bulk (Mix di Indicizzazione e Aggiornamento):

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

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

'

In questo esempio:

1. Il documento 2001 viene indicizzato.
2. Il documento 1001 viene parzialmente aggiornato (il prezzo viene abbassato).
3. Il documento 3003 viene eliminato.

Risposta Bulk: La risposta dettaglierà il successo o il fallimento di ciascuna singola operazione all'interno del batch, permettendoti di individuare quali documenti sono riusciti e quali sono falliti.

---

Riepilogo dei Comandi API Chiave

Operazione	Metodo HTTP	Modello Endpoint	Effetto
Indicizza (ID Auto)	POST	/{index}/_doc/	Crea un nuovo documento con ID generato automaticamente.
Indicizza/Sovrascrivi	PUT	/{index}/_doc/{id}	Crea o sostituisce completamente il documento all'ID specificato.
Aggiornamento Parziale	POST	/{index}/_update/{id}	Unisce le modifiche specificate nel blocco doc.
Operazioni Bulk	POST	/{index}/_bulk	Esegue più operazioni in un'unica richiesta.

Padroneggiare queste interazioni fondamentali della REST API fornisce la base per la gestione dinamica dei dati all'interno di qualsiasi applicazione Elasticsearch.