Runbook: operazioni distruttive di excelSink

Cosa fanno replace e cancellaQuando sul workbook, come si dichiarano e come si torna indietro. Vale per chi possiede la pipeline (l'owner nella sua scheda) e per chi è di turno quando una run ha toccato un file che non doveva.

Chi autorizza. Un nodo excelSink con destructive: true cancella dati dal workbook. La prima esecuzione in produzione la autorizza l'owner della pipeline; non si lancia mai a mano contro il file di un utente senza conferma esplicita.

Cosa fanno

Opzione	Effetto sul foglio di destinazione
mode: "replace"	Toglie tutte le righe sotto l'intestazione e scrive i record del batch. Intestazione, righe sopra l'intestazione, altri fogli e il resto del pacchetto restano. Un batch vuoto non tocca il file.
cancellaQuando + cancellaRighe: "rimuovi" (default)	In upsert, il record che soddisfa la condizione toglie la riga con la sua chiave: le righe sotto salgono e i riferimenti del foglio (formule, tabelle, unioni, formattazioni, convalide, nomi) si riscrivono. Se il layer non sa riscriverli, il nodo fallisce prima di scrivere. Senza la riga, nessun effetto.
cancellaQuando + cancellaRighe: "svuota"	Come sopra ma la riga resta come buco: celle vuote, stile mantenuto, nessuna riga spostata, nessun riferimento toccato.

Con replace la tabella Excel del foglio si restringe alle righe nuove; formattazione condizionale, convalide e celle unite che puntano alle righe tolte restano come sono (il foglio si riscrive, non si ricalcolano). Una tabella con la riga dei totali è rifiutata.

Come si dichiara

excelSink(storage, {
  mode: "replace",
  destructive: true,
  path: "report.xlsx",
  sheet: "Dati",
});

excelSink(storage, {
  mode: "upsert",
  key: ["id"],
  cancellaQuando: { field: "stato", equals: "annullata" },
  cancellaRighe: "rimuovi", // o "svuota"; senza, vale "rimuovi"
  destructive: true,
  path: "note.xlsx",
  sheet: { field: "utente" },
});

destructive: true è obbligatorio: senza, excelSink fa fallire la costruzione del grafo (ConfigError). Il flag compare nel descriptor del nodo (destructive: true), quindi nel DAG e nel report della run; con cancellaQuando compaiono anche il campo e cancellaRighe.

Se "rimuovi" si ferma con un errore che nomina un grafico, una pivot, dei commenti o una formula condivisa, il file è intatto: togli l'elemento dal workbook oppure passa a cancellaRighe: "svuota". La tabella completa di ciò che si riscrive e di ciò che si rifiuta è nella scheda del connettore.

replace non è retrySafe (retry e rateLimit sul nodo fanno fallire build()); upsert con cancellaQuando resta retrySafe: svuotare due volte la stessa riga dà lo stesso foglio.

Prima di eseguire

1. Conferma percorso, foglio e storage nel descriptor del nodo: replace sul foglio sbagliato cancella il foglio sbagliato.
2. Non c'è un backup automatico. Se il file conta, copialo prima nello stesso storage (note.xlsx → note.xlsx.bak-AAAAMMGG), oppure verifica che lo storage tenga le versioni.
3. Il file non deve essere aperto in Excel (~$nome.xlsx): il sink si ferma con un errore transitorio, ed è la risposta giusta.

Come tornare indietro

Il sink scrive con la sostituzione atomica dello storage: o c'è il file vecchio o c'è il nuovo, mai uno a metà. Per annullare una run:

1. Ferma la pipeline, così nessuna run riscrive sopra.
2. Ripristina il file dallo storage (la copia fatta prima, o la versione precedente se lo storage le conserva) sul percorso di path.
3. Riesegui solo quando la causa è chiarita. Con replace la riesecuzione riscrive il foglio con il batch corrente; con cancellaQuando riapplica le cancellazioni ai record che arrivano.

Le righe svuotate o tolte da cancellaQuando non si ricostruiscono dal file nuovo: i valori stanno solo nella copia precedente.

Quando la run fallisce a metà

Il file non viene sostituito se il batch è invalido, se il foglio supera maxSheetBytes, se il file è cambiato mentre il sink lo elaborava o se Excel lo tiene aperto: in tutti questi casi il file resta quello di prima. Ripeti la run dopo aver rimosso la causa.

excelTask: cancellare un foglio o delle colonne

Anche excelTask ha due operazioni che tolgono dati: deleteSheet e deleteColumns. Valgono le stesse regole: destructive: true sul task è obbligatorio (senza, la costruzione fallisce con ConfigError) e compare nel descriptor e nel report. Il task riscrive i riferimenti o rifiuta prima di scrivere, nominando quelli che si romperebbero (#REF!): il file non viene toccato. Si torna indietro come per il sink: dal backup o dalla versione precedente del file; il task non tiene copie.