Tema
Le schede di una pipeline
Ogni pipeline del catalogo ha una scheda, docs/pipelines/<nome>.md nel repo che la contiene, creata insieme alla pipeline e aggiornata nello stesso commit di ogni modifica al comportamento. etl docs build non costruisce il sito se una pipeline del catalogo non ha la sua scheda, cioè una pagina con <PipelineDag name="<nome>" />.
In questa guida ci sono le schede delle pipeline del core, in due sezioni: le pipeline pronte, che un repo cliente dichiara nel suo catalogo e non documenta, e gli esempi, le pipeline di riferimento da cui partire. Le schede delle pipeline di un cliente stanno nella sua documentazione.
Il nome della pipeline è kebab-case, e combacia con processes.function e con scheduled_jobs.process_function: il worker risolve per nome, senza traduzione.
Template scheda
markdown
---
pageClass: etl-wide
---
# Pipeline: <nome>
- **Scopo:** ...
- **Owner:** ...
- **Cadenza:** daily | hourly | on-demand
- **Runbook:** [link](../runbooks/<nome>.md)
## Flusso dati
Una riga sola di contesto, poi il grafo della pipeline:
```md
<PipelineDag name="<nome-della-pipeline>" />
```
Il disegno arriva dal `getSpec()` della pipeline dichiarata nel catalogo `etl.config.ts` — nodi, archi,
dead-letter e ramo catch sono quelli che girano davvero — quindi non si disegna a mano e non
va tenuto allineato. Le istanze di sub-pipeline sono nodi chiusi in cui si entra sul posto, e
`?istanza=<percorso d'istanza>` apre la scheda già dentro un'istanza. Vedi
`orders-enriched-daily` fra gli esempi.
Sotto il grafo il componente genera anche la tabella «Lo scopo dei nodi», dal `purpose` del
builder: gli scopi non si scrivono nella scheda.
## Sorgenti
| Sistema | Schema/tabella | Chiave naturale | Modalità (full/incrementale) |
| ------- | -------------- | --------------- | ---------------------------- |
## Sink
| Sistema | Tabella/destinazione | Idempotenza (upsert/merge/swap) |
| ------- | -------------------- | ------------------------------- |
## Trasformazioni e regole di business
- ... (con riferimento al file `src/pipelines/<nome>/pipeline.ts`)
## Contratti (schema Zod)
- Input: ...
- Output: ...
## Parametri ed env
- `ctx.params`: ... (i parametri di lancio dichiarati con `runParams`, con tipo e obbligatorietà, se ci sono)
- Variabili d'ambiente: ... (anche in `.env.example`)
## Gestione errori
- Cosa finisce nel dead-letter e come si recupera.
## Test
- Riferimento ai test: `src/pipelines/<nome>/pipeline.test.ts`.
## Versioni
Una riga sola di contesto, poi la storia della pipeline:
```md
<PipelineVersions name="<nome-della-pipeline>" />
```
La storia arriva dal changelog della pipeline (`src/pipelines/<nome>/changelog.ts`) e dagli
snapshot del piano di ogni versione (`versions/v<N>.plan.json`): per ogni versione, dalla più
recente, la voce scritta dall'autore e sotto il diff di nodi, archi e colonne rispetto alla
precedente, con «rompe il contratto» se una colonna di un sink sparisce, cambia nome o cambia tipo. Non si
scrive a mano: vedi [versioni di pipeline](../conventions/versioni-di-pipeline.md).