@noeva/etl-core 1.0.1 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +134 -0
- package/README.md +6 -11
- package/dist/{ai-BoTwcmUg.d.ts → ai-DyDIf-hQ.d.ts} +1 -1
- package/dist/{ambiente-della-pipeline-BoymQ6uN.d.ts → ambiente-della-pipeline-BhWsyLUR.d.ts} +2 -2
- package/dist/chunk-47NVGHUY.js +2 -0
- package/dist/chunk-5OE6F2MK.js +2 -0
- package/dist/{chunk-NZR6TZ42.js → chunk-5XVANFXO.js} +1 -1
- package/dist/chunk-672L5BGQ.js +1 -0
- package/dist/{chunk-4NPSBPBY.js → chunk-6QVYBDIS.js} +1 -1
- package/dist/{chunk-PE2QKU34.js → chunk-CEAMQIRO.js} +1 -1
- package/dist/chunk-DHQ3YOPX.js +5 -0
- package/dist/chunk-FBSNZG34.js +1 -0
- package/dist/{chunk-J3PBMWSP.js → chunk-GZWYRO3V.js} +1 -1
- package/dist/chunk-IODXIHU2.js +1 -0
- package/dist/{chunk-P6B2KLNJ.js → chunk-KEFIGSRS.js} +2 -2
- package/dist/chunk-KGWA46Y6.js +2 -0
- package/dist/chunk-L25W2QNS.js +1 -0
- package/dist/{chunk-JLPK6MMQ.js → chunk-OK3XRTGA.js} +1 -1
- package/dist/chunk-UHGHK6NP.js +1 -0
- package/dist/chunk-VL7DZWWO.js +2 -0
- package/dist/chunk-VVXT66DC.js +1 -0
- package/dist/chunk-ZKDCUSM2.js +6 -0
- package/dist/cli.js +2 -2
- package/dist/{client-DYA3wIyb.d.ts → client-BC_mLuT2.d.ts} +2 -2
- package/dist/config-BSdGSRPG.d.ts +37 -0
- package/dist/{config-BSUwK4p_.d.ts → config-DMafsY4H.d.ts} +3 -3
- package/dist/connector-kit.d.ts +14 -9
- package/dist/connector-kit.js +1 -1
- package/dist/connectors/excel.d.ts +391 -0
- package/dist/connectors/excel.js +10 -0
- package/dist/connectors/file.d.ts +12 -5
- package/dist/connectors/file.js +1 -1
- package/dist/connectors/http.d.ts +7 -7
- package/dist/connectors/http.js +1 -1
- package/dist/connectors/imap.d.ts +6 -6
- package/dist/connectors/imap.js +1 -1
- package/dist/connectors/jira.d.ts +6 -6
- package/dist/connectors/jira.js +2 -2
- package/dist/connectors/mail.d.ts +7 -7
- package/dist/connectors/mail.js +1 -1
- package/dist/connectors/mysql.d.ts +238 -0
- package/dist/connectors/mysql.js +2 -0
- package/dist/connectors/noeva.d.ts +6 -6
- package/dist/connectors/noeva.js +1 -1
- package/dist/connectors/oauth.d.ts +5 -5
- package/dist/connectors/oauth.js +1 -1
- package/dist/connectors/odoo.d.ts +309 -0
- package/dist/connectors/odoo.js +3 -0
- package/dist/connectors/postgres.d.ts +7 -6
- package/dist/connectors/postgres.js +1 -1
- package/dist/connectors/process.d.ts +1 -1
- package/dist/connectors/process.js +1 -1
- package/dist/connectors/sendgrid.d.ts +7 -7
- package/dist/connectors/sendgrid.js +1 -1
- package/dist/connectors/smtp.d.ts +8 -8
- package/dist/connectors/smtp.js +1 -1
- package/dist/connectors/sqlserver.d.ts +7 -6
- package/dist/connectors/sqlserver.js +1 -1
- package/dist/connectors/zoho.d.ts +6 -6
- package/dist/connectors/zoho.js +1 -1
- package/dist/contract.d.ts +2 -2
- package/dist/{credenziali-posta-f7HB2cYW.d.ts → credenziali-posta-C0az04uV.d.ts} +2 -2
- package/dist/{errors-bgSO6lGO.d.ts → errors-CRq1uNYZ.d.ts} +8 -1
- package/dist/etl.config.js +3 -3
- package/dist/guida/404.html +2 -2
- package/dist/guida/GUIDA_SVILUPPO.html +7 -7
- package/dist/guida/TECHNICAL_OVERVIEW.html +7 -7
- package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.js → GUIDA_SVILUPPO.md.Bvr7RKHN.js} +2 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.C6HYc5_h.js +10 -0
- package/dist/guida/assets/{app.DeVEBaIz.js → app.uK-5scpr.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.AxYI9rrX.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.CsTQzJUK.js → VPLocalSearchBox.CB5vaMvW.js} +1 -1
- package/dist/guida/assets/chunks/{theme.Dfy0C_Zf.js → theme.z6u0J2Ii.js} +2 -2
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.js +1 -0
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.lean.js +1 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.js +92 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.lean.js +1 -0
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.js → connectors_file.md.Dbofo9W5.js} +3 -3
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.lean.js → connectors_file.md.Dbofo9W5.lean.js} +1 -1
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.js +34 -0
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.lean.js +1 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.js +19 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.lean.js +1 -0
- package/dist/guida/assets/{conventions_node-descriptor.md.MQaGlm8a.js → conventions_node-descriptor.md.C19dB-Tb.js} +4 -4
- package/dist/guida/assets/conventions_node-descriptor.md.C19dB-Tb.lean.js +1 -0
- package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.js → conventions_run-report.md.iVSN9fNV.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.js → conventions_versioni-di-pipeline.md.DJPSthZ8.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.lean.js → conventions_versioni-di-pipeline.md.DJPSthZ8.lean.js} +1 -1
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.js → nodes_README.md.BNAiSoJJ.js} +2 -2
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.lean.js → nodes_README.md.BNAiSoJJ.lean.js} +1 -1
- package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.js → nodes_lookup.md.DrJFsfOJ.js} +1 -1
- package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.js → nodes_sink.md.C1S-lAh2.js} +2 -2
- package/dist/guida/assets/{nodes_source.md.DP2i3GFv.js → nodes_source.md.BitUNtug.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.js → nodes_task.md.CejEQZcD.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.lean.js → nodes_task.md.CejEQZcD.lean.js} +1 -1
- package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.js → nodes_transform.md.Ciycywnb.js} +1 -1
- package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js} +1 -1
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.js +16 -0
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.lean.js +1 -0
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.js → runbooks_sql-task-truncate-swap.md.DAz41942.js} +5 -3
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.lean.js → runbooks_sql-task-truncate-swap.md.DAz41942.lean.js} +1 -1
- package/dist/guida/connectors/README.html +5 -5
- package/dist/guida/connectors/excel.html +118 -0
- package/dist/guida/connectors/file.html +7 -7
- package/dist/guida/connectors/http.html +4 -4
- package/dist/guida/connectors/imap.html +4 -4
- package/dist/guida/connectors/jira.html +5 -5
- package/dist/guida/connectors/mysql.html +60 -0
- package/dist/guida/connectors/noeva.html +5 -5
- package/dist/guida/connectors/oauth.html +5 -5
- package/dist/guida/connectors/odoo.html +45 -0
- package/dist/guida/connectors/postgres.html +5 -5
- package/dist/guida/connectors/process.html +4 -4
- package/dist/guida/connectors/sendgrid.html +4 -4
- package/dist/guida/connectors/smtp.html +4 -4
- package/dist/guida/connectors/sqlserver.html +4 -4
- package/dist/guida/connectors/zoho.html +4 -4
- package/dist/guida/conventions/node-columns.html +4 -4
- package/dist/guida/conventions/node-descriptor.html +8 -8
- package/dist/guida/conventions/run-report.html +6 -6
- package/dist/guida/conventions/run-trace.html +4 -4
- package/dist/guida/conventions/variabili-del-core.html +4 -4
- package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
- package/dist/guida/guide/claude-code/index.html +4 -4
- package/dist/guida/guide/claude-code/prompt.html +5 -5
- package/dist/guida/guide/claude-code/strumenti.html +4 -4
- package/dist/guida/guide/grafo.html +4 -4
- package/dist/guida/guide/usare/app-desktop.html +4 -4
- package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
- package/dist/guida/guide/usare/index.html +4 -4
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +4 -4
- package/dist/guida/nodes/README.html +5 -5
- package/dist/guida/nodes/action.html +4 -4
- package/dist/guida/nodes/ai.html +4 -4
- package/dist/guida/nodes/join.html +4 -4
- package/dist/guida/nodes/lookup.html +6 -6
- package/dist/guida/nodes/pipeline.html +4 -4
- package/dist/guida/nodes/route.html +4 -4
- package/dist/guida/nodes/sink.html +7 -7
- package/dist/guida/nodes/source.html +7 -7
- package/dist/guida/nodes/task.html +6 -6
- package/dist/guida/nodes/transform.html +6 -6
- package/dist/guida/nodes/try-catch.html +4 -4
- package/dist/guida/nodes/union.html +4 -4
- package/dist/guida/pagine.json +4 -0
- package/dist/guida/pipelines/README.html +4 -4
- package/dist/guida/pipelines/crm-leads-sync.html +4 -4
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
- package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
- package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
- package/dist/guida/pipelines/test-posta.html +4 -4
- package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
- package/dist/guida/runbooks/deploy-ecr.html +4 -4
- package/dist/guida/runbooks/deployment.html +6 -6
- package/dist/guida/runbooks/etl-worker.html +5 -5
- package/dist/guida/runbooks/excel-operazioni-distruttive.html +42 -0
- package/dist/guida/runbooks/graph-server.html +5 -5
- package/dist/guida/runbooks/mask-key.html +4 -4
- package/dist/guida/runbooks/oauth-google-posta.html +4 -4
- package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
- package/dist/guida/runbooks/scd2-rehash.html +4 -4
- package/dist/guida/runbooks/sql-task-truncate-swap.html +8 -6
- package/dist/guida/runbooks/stato-incrementale.html +4 -4
- package/dist/guida/sub-pipelines/README.html +4 -4
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
- package/dist/index.d.ts +9 -9
- package/dist/index.js +1 -1
- package/dist/{invio-Dwz3J7sP.d.ts → invio-9Ubb_cdR.d.ts} +3 -3
- package/dist/{istanza-per-il-piano-CucqUF7b.d.ts → istanza-per-il-piano-74NYhIHc.d.ts} +1 -1
- package/dist/{manifest-variabili-U1UfPDfF.d.ts → manifest-variabili-DRWUzmxU.d.ts} +1 -1
- package/dist/pipelines.d.ts +3 -3
- package/dist/pipelines.js +1 -1
- package/dist/{runnable-pipeline-CArkLzfv.d.ts → runnable-pipeline-CWgPwi6w.d.ts} +2 -2
- package/dist/{config-DIthC7n7.d.ts → sql-watermark-CQVvxhPZ.d.ts} +9 -40
- package/dist/testing.d.ts +3 -3
- package/dist/testing.js +1 -1
- package/dist/{trasporto-DpPLCEQ1.d.ts → trasporto-BaRdP6Wl.d.ts} +4 -4
- package/dist/{types-BVA7BIou.d.ts → types-_3rgLhje.d.ts} +21 -2
- package/dist/{variabili-dichiarate-DmfcxsT9.d.ts → variabili-dichiarate-CS-eC53K.d.ts} +1 -1
- package/kit/skills/etl-graph/SKILL.md +6 -3
- package/kit/skills/etl-graph/references/data-patterns.md +1 -1
- package/kit/skills/etl-graph/references/error-handling.md +3 -3
- package/kit/skills/etl-graph/references/wiring.md +10 -10
- package/kit/skills/new-connector/SKILL.md +2 -2
- package/package.json +16 -1
- package/dist/chunk-BVUOUBLW.js +0 -1
- package/dist/chunk-CRR3Q2C7.js +0 -2
- package/dist/chunk-LJ7DVP5F.js +0 -2
- package/dist/chunk-PKBSETMV.js +0 -2
- package/dist/chunk-QPJC4GWR.js +0 -1
- package/dist/chunk-RCRMQPFH.js +0 -5
- package/dist/chunk-RS5SGDUU.js +0 -1
- package/dist/chunk-RWPHH4E2.js +0 -1
- package/dist/chunk-SRFFKE5W.js +0 -6
- package/dist/chunk-WVODQB6Z.js +0 -1
- package/dist/chunk-XZMCC6VQ.js +0 -1
- package/dist/chunk-ZCYGHS7P.js +0 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.DTIhkkg9.js +0 -10
- package/dist/guida/assets/chunks/@localSearchIndexroot.NgfCNDyz.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +0 -1
- package/dist/guida/assets/conventions_node-descriptor.md.MQaGlm8a.lean.js +0 -1
- /package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.lean.js → GUIDA_SVILUPPO.md.Bvr7RKHN.lean.js} +0 -0
- /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js → TECHNICAL_OVERVIEW.md.C6HYc5_h.lean.js} +0 -0
- /package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.lean.js → conventions_run-report.md.iVSN9fNV.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.lean.js → nodes_lookup.md.DrJFsfOJ.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.lean.js → nodes_sink.md.C1S-lAh2.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_source.md.DP2i3GFv.lean.js → nodes_source.md.BitUNtug.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.lean.js → nodes_transform.md.Ciycywnb.lean.js} +0 -0
- /package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.lean.js → runbooks_deployment.md.BV8Izw4I.lean.js} +0 -0
|
@@ -4,7 +4,7 @@ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qd
|
|
|
4
4
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> descriptor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDescriptor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// che cos'è e dove punta, per il DAG</span></span>
|
|
5
5
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> columns</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PlanColumn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// campi emessi, se non c'è uno schema Zod</span></span>
|
|
6
6
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> watermark</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SourceWatermark</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// presente se la source è incrementale</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to "Source pronte""></a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>zohoCrmRecords</code></td><td>Zoho CRM (record di un modulo)</td><td><a href="./../connectors/zoho">zoho</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to "Esempio""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fatture-giornaliere"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to "Source pronte""></a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>mysqlSource</code></td><td>MySQL, MariaDB</td><td><a href="./../connectors/mysql">mysql</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>excelSource</code></td><td>Excel: uno o più fogli, a flusso</td><td><a href="./../connectors/excel">excel</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>zohoCrmRecords</code></td><td>Zoho CRM (record di un modulo)</td><td><a href="./../connectors/zoho">zoho</a></td></tr><tr><td><code>odooRecords</code>, <code>odooConteggi</code></td><td>Odoo (record di un modello)</td><td><a href="./../connectors/odoo">odoo</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to "Esempio""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fatture-giornaliere"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
8
8
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fatture"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.fatture) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Source<unknown>: il contratto lo fa il nodo dopo</span></span>
|
|
9
9
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"clienti"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.clienti)</span></span>
|
|
10
10
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
@@ -29,5 +29,5 @@ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qd
|
|
|
29
29
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> initial: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"1970-01-01 00:00:00"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
30
30
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> lookback: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// opzionale, in millisecondi: copre le transazioni lunghe</span></span>
|
|
31
31
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
32
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Esito della run</th><th>Il watermark avanza?</th></tr></thead><tbody><tr><td><code>success</code></td><td>sì</td></tr><tr><td><code>partial</code></td><td>no, salvo <code>graph(nome, { commitOn: "partial" })</code>, e solo se ogni scarto è una dead-letter per record</td></tr><tr><td><code>failed</code></td><td>mai</td></tr></tbody></table><p>Regole da tenere a mente:</p><ul><li><strong>Il confine è <code>>=</code></strong>, non <code>></code>: due run consecutive senza dati nuovi rileggono le righe al confine. Per questo una source incrementale scrive <strong>solo verso sink idempotenti</strong>.</li><li><strong>Senza il segnaposto <code>:watermark</code> la costruzione fallisce</strong> (source SQL): una query incrementale non degrada in silenzio in un full scan.</li><li><strong>Il watermark è testo</strong>, nella precisione del database: i microsecondi di Postgres non si perdono passando da una <code>Date</code>.</li><li><strong>Lo store lo inietta chi lancia la run</strong> (<code>ctx.stateStore</code>): un file locale per <code>etl run</code>, <code>noeva-server-api</code> per il worker e per <code>etl run --workspace <id></code>. Un grafo con source incrementali non parte senza. Nei test si usa <code>MemoryPipelineStateStore</code>.</li><li><strong>Backfill:</strong> <code>params.watermark.<nodeId></code> sostituisce in lettura il valore salvato, e non fa arretrare lo stato. <strong>Reset:</strong> <code>etl state reset</code>, l'unico modo di farlo arretrare.</li></ul><p>Oggi sono incrementali <code>postgresSource</code>, <code>mssqlSource</code> e <code>jiraIssues</code> con <code>incremental</code> (il filtro su <code>updated</code> lo scrive il connettore: vedi <a href="./../connectors/jira">jira</a>, «Modalità incrementale»). Operatività, diagnosi e procedure: <a href="./../runbooks/stato-incrementale">runbook</a>.</p><h2 id="partire-dopo-un-altro-nodo-after" tabindex="-1">Partire dopo un altro nodo: <code>after</code> <a class="header-anchor" href="#partire-dopo-un-altro-nodo-after" aria-label="Permalink to "Partire dopo un altro nodo: \`after\`""></a></h2><p>Con <code>after</code> la source ha un <strong>gate</strong>: <code>extract()</code> non viene chiamato finché i nodi elencati non sono <strong>riusciti</strong>. Sono <a href="./task"><code>task</code></a> o <code>sink</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordini, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"svuota-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un task: pre-task</span></span>
|
|
32
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Esito della run</th><th>Il watermark avanza?</th></tr></thead><tbody><tr><td><code>success</code></td><td>sì</td></tr><tr><td><code>partial</code></td><td>no, salvo <code>graph(nome, { commitOn: "partial" })</code>, e solo se ogni scarto è una dead-letter per record</td></tr><tr><td><code>failed</code></td><td>mai</td></tr></tbody></table><p>Regole da tenere a mente:</p><ul><li><strong>Il confine è <code>>=</code></strong>, non <code>></code>: due run consecutive senza dati nuovi rileggono le righe al confine. Per questo una source incrementale scrive <strong>solo verso sink idempotenti</strong>.</li><li><strong>Senza il segnaposto <code>:watermark</code> la costruzione fallisce</strong> (source SQL): una query incrementale non degrada in silenzio in un full scan.</li><li><strong>Il watermark è testo</strong>, nella precisione del database: i microsecondi di Postgres non si perdono passando da una <code>Date</code>.</li><li><strong>Lo store lo inietta chi lancia la run</strong> (<code>ctx.stateStore</code>): un file locale per <code>etl run</code>, <code>noeva-server-api</code> per il worker e per <code>etl run --workspace <id></code>. Un grafo con source incrementali non parte senza. Nei test si usa <code>MemoryPipelineStateStore</code>.</li><li><strong>Backfill:</strong> <code>params.watermark.<nodeId></code> sostituisce in lettura il valore salvato, e non fa arretrare lo stato. <strong>Reset:</strong> <code>etl state reset</code>, l'unico modo di farlo arretrare.</li></ul><p>Oggi sono incrementali <code>postgresSource</code>, <code>mssqlSource</code>, <code>mysqlSource</code> e <code>jiraIssues</code> con <code>incremental</code> (il filtro su <code>updated</code> lo scrive il connettore: vedi <a href="./../connectors/jira">jira</a>, «Modalità incrementale»). Operatività, diagnosi e procedure: <a href="./../runbooks/stato-incrementale">runbook</a>.</p><h2 id="partire-dopo-un-altro-nodo-after" tabindex="-1">Partire dopo un altro nodo: <code>after</code> <a class="header-anchor" href="#partire-dopo-un-altro-nodo-after" aria-label="Permalink to "Partire dopo un altro nodo: \`after\`""></a></h2><p>Con <code>after</code> la source ha un <strong>gate</strong>: <code>extract()</code> non viene chiamato finché i nodi elencati non sono <strong>riusciti</strong>. Sono <a href="./task"><code>task</code></a> o <code>sink</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordini, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"svuota-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un task: pre-task</span></span>
|
|
33
33
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fatti"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fatti, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"carica-dimensioni"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un sink: dimensioni prima dei fatti</span></span></code></pre></div><ul><li>Più nodi in <code>after</code> valgono in AND.</li><li>Tutto ciò che sta a valle aspetta con lei: un lookup sui fatti legge le dimensioni già caricate, e un sink a valle non chiama <code>load</code> finché il gate non si apre.</li><li>Se un predecessore non è riuscito la source è <strong>saltata</strong>: <code>extract()</code> non viene mai chiamato, e i nodi a valle sono saltati con lei. Vedi <a href="./task#nodi-saltati"><code>task</code></a>.</li><li><code>build()</code> rifiuta un <code>after</code> che crea un ciclo (il sink alimentato dalla source stessa) o un deadlock su un <code>join</code> o un <code>union</code> a valle.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to "Errori""></a></h2><p><code>extract</code> è un contratto <strong>opaco</strong>: non isola il singolo record. Un errore di estrazione (<code>ExtractError</code>) interrompe la run, anche sotto un <code>try-catch</code>, perché la source sta a monte di ogni scope. Il retry non si applica alle source: rileggere non è sempre senza effetti.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to "Nel DAG e nel report""></a></h2><p>Il nodo mostra il <code>descriptor</code> (tipo di connettore, istanza, puntamenti; mai segreti) e le colonne dichiarate in <code>columns</code>. Nel report, <code>extracted</code> conta i record emessi. Una source saltata ha <code>skipped: { because }</code> e <code>startedAt: null</code>. Una source incrementale ha anche una voce in <a href="./../conventions/run-report#stato-di-pipeline-state"><code>state</code></a>: da dove ha letto, cosa propone, se ha committato.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to "Anti-pattern""></a></h2><ul><li><code>Array.fromAsync(source.extract(ctx))</code>, o qualunque cosa che legga tutto in memoria: si perde lo streaming e con lui la backpressure.</li><li>Istanziare il client o il pool dentro <code>build…Pipeline</code>: va iniettato.</li></ul>`,29))])}const F=t(h,[["render",p]]);export{m as __pageData,F as default};
|
|
@@ -4,10 +4,10 @@ import{_ as s,C as o,o as n,c as r,j as a,a as i,E as l,a5 as d}from"./chunks/fr
|
|
|
4
4
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> descriptor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDescriptor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// su che cosa opera, per il DAG</span></span>
|
|
5
5
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> retrySafe</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> boolean</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// rieseguirlo non cambia il risultato</span></span>
|
|
6
6
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> writeReport</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> WriteReportFn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// i dettagli nel report, es. le righe toccate</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>ctx.signal</code> è il segnale della run e <strong>va rispettato</strong>: quando la run viene annullata il runner aspetta che <code>run</code> termini, senza timeout, perché un'operazione abbandonata a metà lascia lo stato del sistema esterno ignoto.</p><h2 id="task-pronti" tabindex="-1">Task pronti <a class="header-anchor" href="#task-pronti" aria-label="Permalink to "Task pronti""></a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Cosa fa</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSqlTask</code></td><td>PostgreSQL</td><td>Statement statici in una transazione</td><td><a href="./../connectors/postgres#task--postgressqltask">postgres</a></td></tr><tr><td><code>mssqlSqlTask</code></td><td>SQL Server</td><td>Statement statici in una transazione</td><td><a href="./../connectors/sqlserver#task--mssqlsqltask">sqlserver</a></td></tr></tbody></table><p>Un task SQL con <code>destructive: true</code> cancella o sostituisce dati: prima di usarlo in produzione leggi il <a href="./../runbooks/sql-task-truncate-swap">runbook</a>.</p><h2 id="edge-di-controllo-after" tabindex="-1">Edge di controllo: <code>after</code> <a class="header-anchor" href="#edge-di-controllo-after" aria-label="Permalink to "Edge di controllo: \`after\`""></a></h2><p>Un edge di controllo dice «B parte solo dopo che A è <strong>riuscito</strong>». Non porta record. Si scrive con l'opzione <code>after</code> dei due soli nodi che possono aspettare, <code>.task()</code> e <code>.source()</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini-swap"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>ctx.signal</code> è il segnale della run e <strong>va rispettato</strong>: quando la run viene annullata il runner aspetta che <code>run</code> termini, senza timeout, perché un'operazione abbandonata a metà lascia lo stato del sistema esterno ignoto.</p><h2 id="task-pronti" tabindex="-1">Task pronti <a class="header-anchor" href="#task-pronti" aria-label="Permalink to "Task pronti""></a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Cosa fa</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSqlTask</code></td><td>PostgreSQL</td><td>Statement statici in una transazione</td><td><a href="./../connectors/postgres#task--postgressqltask">postgres</a></td></tr><tr><td><code>mssqlSqlTask</code></td><td>SQL Server</td><td>Statement statici in una transazione</td><td><a href="./../connectors/sqlserver#task--mssqlsqltask">sqlserver</a></td></tr><tr><td><code>mysqlSqlTask</code></td><td>MySQL, MariaDB</td><td>Statement statici in una transazione (il DDL fa commit implicito)</td><td><a href="./../connectors/mysql#task--mysqlsqltask">mysql</a></td></tr><tr><td><code>excelTask</code></td><td>Excel</td><td>Operazioni sul workbook: fogli e colonne (riordina, rinomina, cancella, inserisci)</td><td><a href="./../connectors/excel#exceltask-operazioni-senza-record">excel</a></td></tr></tbody></table><p>Un task SQL con <code>destructive: true</code> cancella o sostituisce dati: prima di usarlo in produzione leggi il <a href="./../runbooks/sql-task-truncate-swap">runbook</a>. Lo stesso vale per <code>excelTask</code> con <code>deleteSheet</code> o <code>deleteColumns</code>: <a href="./../runbooks/excel-operazioni-distruttive">runbook delle operazioni distruttive di Excel</a>.</p><h2 id="edge-di-controllo-after" tabindex="-1">Edge di controllo: <code>after</code> <a class="header-anchor" href="#edge-di-controllo-after" aria-label="Permalink to "Edge di controllo: \`after\`""></a></h2><p>Un edge di controllo dice «B parte solo dopo che A è <strong>riuscito</strong>». Non porta record. Si scrive con l'opzione <code>after</code> dei due soli nodi che possono aspettare, <code>.task()</code> e <code>.source()</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini-swap"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
8
8
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"svuota-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, svuota)</span></span>
|
|
9
9
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordini, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"svuota-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// pre-task</span></span>
|
|
10
10
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"contratto"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">validate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"contratto"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordineSchema))</span></span>
|
|
11
11
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"contratto"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, staging) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// l'id del nodo è staging.name: "carica-staging"</span></span>
|
|
12
12
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"scambia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, scambia, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"carica-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// post-task</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Da → a</th><th>Si usa per</th></tr></thead><tbody><tr><td><code>task → source</code></td><td><strong>pre-task</strong>: finisce prima che la source estragga il primo record</td></tr><tr><td><code>sink → task</code></td><td><strong>post-task</strong>: parte dopo che il sink ha finito di scrivere</td></tr><tr><td><code>sink → source</code></td><td>un ramo prima di un altro: le dimensioni prima dei fatti</td></tr><tr><td><code>task → task</code></td><td>una catena di operazioni</td></tr></tbody></table><ul><li><strong>Parte da un nodo che finisce</strong> (<code>task</code>, <code>sink</code>) <strong>e arriva a un nodo che inizia</strong> (<code>task</code>, <code>source</code>). Mai da o verso un nodo in mezzo al flusso: <code>build()</code> lo rifiuta e indica l'alternativa.</li><li><strong>Più predecessori valgono in AND</strong>: <code>after: ["a", "b"]</code> aspetta entrambi.</li><li><strong>Solo sul successo</strong>: non esiste un edge «se fallisce». Per gestire gli errori c'è il <a href="./try-catch"><code>try-catch</code></a>.</li><li>Un task <strong>senza</strong> <code>after</code> parte all'avvio della run. Restano obbligatori almeno una source e un sink: un grafo di soli task non si costruisce.</li><li>Un lookup a valle di una source con <code>after</code> parte anch'esso dopo: <code>sink(dimensioni) → source(fatti)</code> copre anche «il lookup dei fatti legge le dimensioni appena caricate».</li></ul><h2 id="quando-il-predecessore-e-«riuscito»" tabindex="-1">Quando il predecessore è «riuscito» <a class="header-anchor" href="#quando-il-predecessore-e-«riuscito»" aria-label="Permalink to "Quando il predecessore è «riuscito»""></a></h2><p>A <strong>non</strong> fa partire i suoi successori se:</p><ul><li>è fallito, <strong>anche se l'errore è stato catturato</strong> da un <code>try-catch</code> (un sink nello scope di un guard);</li><li>oppure il suo input è stato <strong>troncato</strong>: un guard ha catturato l'errore di un nodo a monte e ne ha chiuso lo stream. Conta l'evento, non i record mancanti: vale anche se l'errore arriva dopo l'ultimo record, come il verdetto di un <code>assert</code> in streaming. Il sink ha scritto, e il suo <code>load</code> si è chiuso senza errori, ma lo scambio non deve partire su dati che un controllo ha rifiutato;</li><li>oppure è stato saltato.</li></ul><p><strong>Non</strong> bloccano i rifiuti per record: la <code>deadLetter</code> di un nodo e i record che un guard <code>per-record</code> manda sul ramo <code>catch</code>. Sono un percorso previsto, il resto dei record è arrivato, e la run è <code>partial</code>.</p><blockquote><p><strong>«Nessuno scarto, altrimenti niente scambio».</strong> Un <a href="./transform#controlli-sul-dataset-assert"><code>assert</code></a> prima del sink <strong>non</strong> basta: vede solo i record che gli arrivano, non quelli già finiti in dead-letter a monte. Per la regola rigida togli <code>deadLetter</code> e guard <code>per-record</code> a monte del sink dello staging: il primo record non valido fa fallire la run, e lo scambio non parte.</p></blockquote><h2 id="nodi-saltati" tabindex="-1">Nodi saltati <a class="header-anchor" href="#nodi-saltati" aria-label="Permalink to "Nodi saltati""></a></h2><p>Un nodo che non parte perché un predecessore di controllo non è riuscito è <strong>saltato</strong>. Nel report ha <code>skipped: { because }</code>, <code>success: false</code> e <code>startedAt: null</code>.</p><ul><li>Una <strong>source</strong> saltata porta con sé i suoi <strong>discendenti di dati</strong>: transform, join, sink. Un sink saltato <strong>non chiama mai <code>load</code></strong>, così un sink di file non riscrive il file vuoto. Sono saltati anche i nodi a monte che alimentano soltanto nodi saltati, perché nessuno li tirerebbe.</li><li>Un sink alimentato da più source scrive solo quando i gate di <strong>tutte</strong> sono aperti: con <code>union(S1, S2 con after)</code>, se <code>S2</code> è saltata il sink non scrive nemmeno la parte di <code>S1</code>.</li><li><code>because</code> è l'id del predecessore di controllo che non è riuscito; i discendenti di una source saltata portano lo stesso <code>because</code> della source.</li><li>Il ramo <code>catch</code> di un guard che sta nel sotto-grafo saltato si chiude con zero errori: il suo sink non è saltato.</li></ul><h2 id="errori-e-annullamento" tabindex="-1">Errori e annullamento <a class="header-anchor" href="#errori-e-annullamento" aria-label="Permalink to "Errori e annullamento""></a></h2><table tabindex="0"><thead><tr><th>Caso</th><th>Esito</th></tr></thead><tbody><tr><td>Il task fallisce</td><td>run <code>failed</code>; i successori di controllo e i loro discendenti di dati sono saltati</td></tr><tr><td>Un successore è saltato per un errore <strong>catturato</strong> a monte</td><td>run <code>partial</code></td></tr><tr><td>La run viene annullata a metà task</td><td>il runner aspetta <code>run</code>; il task ha <code>startedAt</code> valorizzato e <code>success: false</code>, non è saltato</td></tr><tr><td>Un altro nodo fa fallire la run</td><td>i gate si chiudono: nessun task parte dopo che la run è fallita</td></tr></tbody></table><p>Un task non sta mai nello scope di un <code>try-catch</code>: lo scope segue gli edge di dati, e gli edge di controllo non lo estendono. Non esiste un task «opzionale»: un <code>ANALYZE</code> che fallisce rende <code>failed</code> una run con i dati già caricati.</p><p><strong>Fail-fast fra rami.</strong> Al primo errore fatale il runner annulla la run e aspetta che <strong>tutti</strong> i sink e i task chiudano, poi riporta la run <code>failed</code>. Vale per ogni grafo, anche senza task: un ramo indipendente non continua a scrivere dopo che la run è fallita.</p><h2 id="retry-e-rate-limit" tabindex="-1">Retry e rate limit <a class="header-anchor" href="#retry-e-rate-limit" aria-label="Permalink to "Retry e rate limit""></a></h2><p>Come sul sink: <code>retry</code> e <code>rateLimit</code> sono ammessi solo se il task dichiara <code>retrySafe: true</code>, altrimenti la costruzione del grafo fallisce. Si ritenta solo un errore <strong>transitorio</strong>, e l'attesa si interrompe con l'annullamento della run. Un <code>TRUNCATE</code> o un <code>ANALYZE</code> sono ripetibili; uno scambio per rename no.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"analizza"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, analizza, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"scambia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">], retry: { attempts: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// solo se retrySafe</span></span></code></pre></div><h2 id="le-regole-che-build-fa-rispettare" tabindex="-1">Le regole che <code>build()</code> fa rispettare <a class="header-anchor" href="#le-regole-che-build-fa-rispettare" aria-label="Permalink to "Le regole che \`build()\` fa rispettare""></a></h2><ul><li>un edge di controllo parte da un <code>task</code> o da un <code>sink</code> e arriva a un <code>task</code> o a una <code>source</code>;</li><li>niente cicli sull'<strong>unione</strong> di edge di dati e di controllo: <code>sink → source</code> sulla source che alimenta quel sink è un ciclo;</li><li>niente <strong>deadlock senza ciclo</strong>: <code>A ⇢ B</code> è rifiutato se un <code>join</code> o un <code>union</code> a valle di <code>B</code> ha un antenato di dati in comune con <code>A</code>. Il fan-in aspetterebbe <code>B</code>, il suo ramo dall'antenato comune si riempirebbe, e <code>A</code> non finirebbe mai. Il messaggio nomina l'antenato: si risolve leggendolo con una source per ramo;</li><li>un task non ha edge di dati, in nessuna direzione;</li><li><code>retry</code> e <code>rateLimit</code> solo su un task <code>retrySafe</code>.</li></ul><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to "Nel DAG e nel report""></a></h2><p>Nel piano (<code>getSpec()</code>) un task ha <code>stepType: "task"</code>, <code>columns: []</code> e il suo <code>descriptor</code>. Gli edge di controllo stanno in <code>edges</code> con <code>kind: "control"</code>, id <code><from>-><to>:control</code>, senza porte.</p><p>Nel report il task è un nodo con <code>kind: "task"</code>: <code>extracted</code>, <code>written</code> e <code>rejected</code> restano a 0, e i tempi sono quelli di <code>run</code>. I dettagli (le righe toccate da un task SQL) vanno in <code>nodeReports</code>, dal <code>writeReport</code> del nodo o da quello dichiarato dal task. <code>retries</code> compare con una policy di <code>retry</code>. Gli <code>edges</code> del report restano quelli di dati. <code>onNodeStart</code> arriva all'ingresso in <code>run</code>, <code>onNodeComplete</code> all'uscita; un nodo saltato notifica solo il completamento, così <code>progress</code> arriva a 100, e il completamento porta già <code>skipped: { because }</code>.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to "Anti-pattern""></a></h2><ul><li>Un <code>TRUNCATE</code> dentro il <code>load</code> di un sink, o in <code>run.ts</code> prima della pipeline: il DAG non lo mostra e il report non lo misura. È un pre-task.</li><li><code>TRUNCATE</code> sulla tabella <strong>in uso</strong> seguito dal caricamento: fra i due la tabella è vuota. Si carica uno staging e lo si scambia.</li><li>Uno scambio con <code>retry</code>: ripeterlo riporta le tabelle com'erano. Non è <code>retrySafe</code>.</li><li>Statement SQL composti con valori della run: i valori entrano solo come parametri bind.</li><li>Un post-task come unica garanzia di qualità con <code>deadLetter</code> a monte: gli scarti non lo fermano.</li></ul>`,39))])}const b=s(c,[["render",p]]);export{y as __pageData,b as default};
|
|
13
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Da → a</th><th>Si usa per</th></tr></thead><tbody><tr><td><code>task → source</code></td><td><strong>pre-task</strong>: finisce prima che la source estragga il primo record</td></tr><tr><td><code>sink → task</code></td><td><strong>post-task</strong>: parte dopo che il sink ha finito di scrivere</td></tr><tr><td><code>sink → source</code></td><td>un ramo prima di un altro: le dimensioni prima dei fatti</td></tr><tr><td><code>task → task</code></td><td>una catena di operazioni</td></tr></tbody></table><ul><li><strong>Parte da un nodo che finisce</strong> (<code>task</code>, <code>sink</code>) <strong>e arriva a un nodo che inizia</strong> (<code>task</code>, <code>source</code>). Mai da o verso un nodo in mezzo al flusso: <code>build()</code> lo rifiuta e indica l'alternativa.</li><li><strong>Più predecessori valgono in AND</strong>: <code>after: ["a", "b"]</code> aspetta entrambi.</li><li><strong>Solo sul successo</strong>: non esiste un edge «se fallisce». Per gestire gli errori c'è il <a href="./try-catch"><code>try-catch</code></a>.</li><li>Un task <strong>senza</strong> <code>after</code> parte all'avvio della run. Restano obbligatori almeno una source e un sink: un grafo di soli task non si costruisce.</li><li>Un lookup a valle di una source con <code>after</code> parte anch'esso dopo: <code>sink(dimensioni) → source(fatti)</code> copre anche «il lookup dei fatti legge le dimensioni appena caricate».</li></ul><h2 id="quando-il-predecessore-e-«riuscito»" tabindex="-1">Quando il predecessore è «riuscito» <a class="header-anchor" href="#quando-il-predecessore-e-«riuscito»" aria-label="Permalink to "Quando il predecessore è «riuscito»""></a></h2><p>A <strong>non</strong> fa partire i suoi successori se:</p><ul><li>è fallito, <strong>anche se l'errore è stato catturato</strong> da un <code>try-catch</code> (un sink nello scope di un guard);</li><li>oppure il suo input è stato <strong>troncato</strong>: un guard ha catturato l'errore di un nodo a monte e ne ha chiuso lo stream. Conta l'evento, non i record mancanti: vale anche se l'errore arriva dopo l'ultimo record, come il verdetto di un <code>assert</code> in streaming. Il sink ha scritto, e il suo <code>load</code> si è chiuso senza errori, ma lo scambio non deve partire su dati che un controllo ha rifiutato;</li><li>oppure è stato saltato.</li></ul><p><strong>Non</strong> bloccano i rifiuti per record: la <code>deadLetter</code> di un nodo e i record che un guard <code>per-record</code> manda sul ramo <code>catch</code>. Sono un percorso previsto, il resto dei record è arrivato, e la run è <code>partial</code>.</p><blockquote><p><strong>«Nessuno scarto, altrimenti niente scambio».</strong> Un <a href="./transform#controlli-sul-dataset-assert"><code>assert</code></a> prima del sink <strong>non</strong> basta: vede solo i record che gli arrivano, non quelli già finiti in dead-letter a monte. Per la regola rigida togli <code>deadLetter</code> e guard <code>per-record</code> a monte del sink dello staging: il primo record non valido fa fallire la run, e lo scambio non parte.</p></blockquote><h2 id="nodi-saltati" tabindex="-1">Nodi saltati <a class="header-anchor" href="#nodi-saltati" aria-label="Permalink to "Nodi saltati""></a></h2><p>Un nodo che non parte perché un predecessore di controllo non è riuscito è <strong>saltato</strong>. Nel report ha <code>skipped: { because }</code>, <code>success: false</code> e <code>startedAt: null</code>.</p><ul><li>Una <strong>source</strong> saltata porta con sé i suoi <strong>discendenti di dati</strong>: transform, join, sink. Un sink saltato <strong>non chiama mai <code>load</code></strong>, così un sink di file non riscrive il file vuoto. Sono saltati anche i nodi a monte che alimentano soltanto nodi saltati, perché nessuno li tirerebbe.</li><li>Un sink alimentato da più source scrive solo quando i gate di <strong>tutte</strong> sono aperti: con <code>union(S1, S2 con after)</code>, se <code>S2</code> è saltata il sink non scrive nemmeno la parte di <code>S1</code>.</li><li><code>because</code> è l'id del predecessore di controllo che non è riuscito; i discendenti di una source saltata portano lo stesso <code>because</code> della source.</li><li>Il ramo <code>catch</code> di un guard che sta nel sotto-grafo saltato si chiude con zero errori: il suo sink non è saltato.</li></ul><h2 id="errori-e-annullamento" tabindex="-1">Errori e annullamento <a class="header-anchor" href="#errori-e-annullamento" aria-label="Permalink to "Errori e annullamento""></a></h2><table tabindex="0"><thead><tr><th>Caso</th><th>Esito</th></tr></thead><tbody><tr><td>Il task fallisce</td><td>run <code>failed</code>; i successori di controllo e i loro discendenti di dati sono saltati</td></tr><tr><td>Un successore è saltato per un errore <strong>catturato</strong> a monte</td><td>run <code>partial</code></td></tr><tr><td>La run viene annullata a metà task</td><td>il runner aspetta <code>run</code>; il task ha <code>startedAt</code> valorizzato e <code>success: false</code>, non è saltato</td></tr><tr><td>Un altro nodo fa fallire la run</td><td>i gate si chiudono: nessun task parte dopo che la run è fallita</td></tr></tbody></table><p>Un task non sta mai nello scope di un <code>try-catch</code>: lo scope segue gli edge di dati, e gli edge di controllo non lo estendono. Non esiste un task «opzionale»: un <code>ANALYZE</code> che fallisce rende <code>failed</code> una run con i dati già caricati.</p><p><strong>Fail-fast fra rami.</strong> Al primo errore fatale il runner annulla la run e aspetta che <strong>tutti</strong> i sink e i task chiudano, poi riporta la run <code>failed</code>. Vale per ogni grafo, anche senza task: un ramo indipendente non continua a scrivere dopo che la run è fallita.</p><h2 id="retry-e-rate-limit" tabindex="-1">Retry e rate limit <a class="header-anchor" href="#retry-e-rate-limit" aria-label="Permalink to "Retry e rate limit""></a></h2><p>Come sul sink: <code>retry</code> e <code>rateLimit</code> sono ammessi solo se il task dichiara <code>retrySafe: true</code>, altrimenti la costruzione del grafo fallisce. Si ritenta solo un errore <strong>transitorio</strong>, e l'attesa si interrompe con l'annullamento della run. Un <code>TRUNCATE</code> o un <code>ANALYZE</code> sono ripetibili; uno scambio per rename no.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"analizza"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, analizza, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"scambia"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">], retry: { attempts: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// solo se retrySafe</span></span></code></pre></div><h2 id="le-regole-che-build-fa-rispettare" tabindex="-1">Le regole che <code>build()</code> fa rispettare <a class="header-anchor" href="#le-regole-che-build-fa-rispettare" aria-label="Permalink to "Le regole che \`build()\` fa rispettare""></a></h2><ul><li>un edge di controllo parte da un <code>task</code> o da un <code>sink</code> e arriva a un <code>task</code> o a una <code>source</code>;</li><li>niente cicli sull'<strong>unione</strong> di edge di dati e di controllo: <code>sink → source</code> sulla source che alimenta quel sink è un ciclo;</li><li>niente <strong>deadlock senza ciclo</strong>: <code>A ⇢ B</code> è rifiutato se un <code>join</code> o un <code>union</code> a valle di <code>B</code> ha un antenato di dati in comune con <code>A</code>. Il fan-in aspetterebbe <code>B</code>, il suo ramo dall'antenato comune si riempirebbe, e <code>A</code> non finirebbe mai. Il messaggio nomina l'antenato: si risolve leggendolo con una source per ramo;</li><li>un task non ha edge di dati, in nessuna direzione;</li><li><code>retry</code> e <code>rateLimit</code> solo su un task <code>retrySafe</code>.</li></ul><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to "Nel DAG e nel report""></a></h2><p>Nel piano (<code>getSpec()</code>) un task ha <code>stepType: "task"</code>, <code>columns: []</code> e il suo <code>descriptor</code>. Gli edge di controllo stanno in <code>edges</code> con <code>kind: "control"</code>, id <code><from>-><to>:control</code>, senza porte.</p><p>Nel report il task è un nodo con <code>kind: "task"</code>: <code>extracted</code>, <code>written</code> e <code>rejected</code> restano a 0, e i tempi sono quelli di <code>run</code>. I dettagli (le righe toccate da un task SQL) vanno in <code>nodeReports</code>, dal <code>writeReport</code> del nodo o da quello dichiarato dal task. <code>retries</code> compare con una policy di <code>retry</code>. Gli <code>edges</code> del report restano quelli di dati. <code>onNodeStart</code> arriva all'ingresso in <code>run</code>, <code>onNodeComplete</code> all'uscita; un nodo saltato notifica solo il completamento, così <code>progress</code> arriva a 100, e il completamento porta già <code>skipped: { because }</code>.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to "Anti-pattern""></a></h2><ul><li>Un <code>TRUNCATE</code> dentro il <code>load</code> di un sink, o in <code>run.ts</code> prima della pipeline: il DAG non lo mostra e il report non lo misura. È un pre-task.</li><li><code>TRUNCATE</code> sulla tabella <strong>in uso</strong> seguito dal caricamento: fra i due la tabella è vuota. Si carica uno staging e lo si scambia.</li><li>Uno scambio con <code>retry</code>: ripeterlo riporta le tabelle com'erano. Non è <code>retrySafe</code>.</li><li>Statement SQL composti con valori della run: i valori entrano solo come parametri bind.</li><li>Un post-task come unica garanzia di qualità con <code>deadLetter</code> a monte: gli scarti non lo fermano.</li></ul>`,39))])}const f=s(c,[["render",p]]);export{y as __pageData,f as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as s,C as o,o as n,c as r,j as a,a as i,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const y=JSON.parse('{"title":"Nodo: task","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/task.md","filePath":"nodes/task.md"}'),c={name:"nodes/task.md"};function p(h,e,k,u,g,E){const t=o("NodeDemo");return n(),r("div",null,[e[0]||(e[0]=a("h1",{id:"nodo-task",tabindex:"-1"},[i("Nodo: task "),a("a",{class:"header-anchor",href:"#nodo-task","aria-label":'Permalink to "Nodo: task"'},"")],-1)),e[1]||(e[1]=a("p",null,[i("Un'operazione "),a("strong",null,"senza flusso di record"),i(": svuotare uno staging, scambiare due tabelle, un "),a("code",null,"ANALYZE"),i(", il refresh di una vista materializzata. Non riceve e non emette record: quando parte lo decidono gli "),a("strong",null,"edge di controllo"),i(", non il flusso dei dati.")],-1)),l(t,{kind:"task"}),e[2]||(e[2]=d("",39))])}const
|
|
1
|
+
import{_ as s,C as o,o as n,c as r,j as a,a as i,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const y=JSON.parse('{"title":"Nodo: task","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/task.md","filePath":"nodes/task.md"}'),c={name:"nodes/task.md"};function p(h,e,k,u,g,E){const t=o("NodeDemo");return n(),r("div",null,[e[0]||(e[0]=a("h1",{id:"nodo-task",tabindex:"-1"},[i("Nodo: task "),a("a",{class:"header-anchor",href:"#nodo-task","aria-label":'Permalink to "Nodo: task"'},"")],-1)),e[1]||(e[1]=a("p",null,[i("Un'operazione "),a("strong",null,"senza flusso di record"),i(": svuotare uno staging, scambiare due tabelle, un "),a("code",null,"ANALYZE"),i(", il refresh di una vista materializzata. Non riceve e non emette record: quando parte lo decidono gli "),a("strong",null,"edge di controllo"),i(", non il flusso dei dati.")],-1)),l(t,{kind:"task"}),e[2]||(e[2]=d("",39))])}const f=s(c,[["render",p]]);export{y as __pageData,f as default};
|
|
@@ -147,7 +147,7 @@ import{_ as n,C as t,o,c as l,j as s,a,E as d,a5 as r}from"./chunks/framework.qd
|
|
|
147
147
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> threshold: { expected: totaleAtteso },</span></span>
|
|
148
148
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
|
|
149
149
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
|
|
150
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}))</span></span></code></pre></div><h3 id="i-check" tabindex="-1">I check <a class="header-anchor" href="#i-check" aria-label="Permalink to "I check""></a></h3><table tabindex="0"><thead><tr><th>Check</th><th>Osserva</th><th>Supera se</th></tr></thead><tbody><tr><td><code>rowCount({ min?, max? })</code></td><td>il numero di record</td><td>sta fra <code>min</code> e <code>max</code>; ne serve almeno uno</td></tr><tr><td><code>nullRatio(colonna, { max })</code></td><td>la quota di null della colonna, fra 0 e 1</td><td>non supera <code>max</code></td></tr><tr><td><code>unique(colonna | colonne[], { maxKeys? })</code></td><td>i record la cui chiave era già comparsa</td><td>sono zero</td></tr><tr><td><code>custom(nome, { init, step, verdict, threshold? })</code></td><td>ciò che restituisce <code>verdict</code></td><td><code>verdict</code> restituisce <code>ok: true</code></td></tr></tbody></table><p>Ogni check accetta <code>severity</code>: <code>"error"</code> (default) ferma la run, <code>"warn"</code> la lascia proseguire.</p><ul><li><strong>Soglie inclusive</strong>: <code>max: 0.05</code> accetta esattamente il 5 %.</li><li><strong>Null</strong> è <code>null</code>, <code>undefined</code> o chiave assente. La stringa vuota è un valore.</li><li><code>nullRatio</code> su <strong>zero record</strong> supera, con osservato <code>null</code>: che zero record siano un problema lo dice <code>rowCount</code>.</li><li><code>unique</code> <strong>ignora i record con la chiave null</strong>; con una chiave composta basta una colonna null. Riporta quanti duplicati ha visto, mai quali.</li><li><code>unique</code> ricorda le chiavi viste, in entrambe le modalità: ha un tetto di memoria proprio, <code>maxKeys</code> (default 100 000). Superarlo ferma la run anche se il check è <code>warn</code>: è un tetto di memoria, non un esito.</li><li><code>custom</code> è un reducer puro: niente IO, niente stato fuori da quello che <code>init</code> crea. L'osservato è un numero o un booleano, perché finisce nel report. <code>threshold</code> serve solo al report e al messaggio d'errore.</li><li><strong>I nomi dei check sono derivati</strong> (<code>rowCount</code>, <code>nullRatio(email)</code>, <code>unique(anno,numero)</code>); <code>custom</code> vuole un nome esplicito. Due check con lo stesso nome nello stesso <code>assert</code> fanno lanciare <code>assert()</code> alla costruzione.</li></ul><h3 id="gate-o-streaming" tabindex="-1">Gate o streaming <a class="header-anchor" href="#gate-o-streaming" aria-label="Permalink to "Gate o streaming""></a></h3><p><code>mode</code> decide quando escono i record.</p><ul><li><strong><code>"gate"</code> (default)</strong> trattiene tutti i record finché il verdetto non è noto, e li emette nello stesso ordine solo se nessun check <code>error</code> è fallito. Se fallisce, a valle non arriva niente. Costa memoria: fino a <code>maxRecords</code> record (default 100 000). Oltre il tetto la run si ferma con un <code>Error</code> semplice, che nessun <code>try-catch</code> assorbe, prima che a valle arrivi un record.</li><li><strong><code>"streaming"</code></strong> emette i record man mano e lancia dopo l'ultimo. Non trattiene niente, ma quando il verdetto arriva il caricamento a valle è già avvenuto.</li></ul><p><strong>La regola: streaming solo se il caricamento a valle è annullabile.</strong> Questa è la matrice, e vive solo qui:</p><table tabindex="0"><thead><tr><th>Caricamento a valle dell'<code>assert</code></th><th>Streaming protegge?</th><th>Perché</th></tr></thead><tbody><tr><td>Sink Postgres
|
|
150
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}))</span></span></code></pre></div><h3 id="i-check" tabindex="-1">I check <a class="header-anchor" href="#i-check" aria-label="Permalink to "I check""></a></h3><table tabindex="0"><thead><tr><th>Check</th><th>Osserva</th><th>Supera se</th></tr></thead><tbody><tr><td><code>rowCount({ min?, max? })</code></td><td>il numero di record</td><td>sta fra <code>min</code> e <code>max</code>; ne serve almeno uno</td></tr><tr><td><code>nullRatio(colonna, { max })</code></td><td>la quota di null della colonna, fra 0 e 1</td><td>non supera <code>max</code></td></tr><tr><td><code>unique(colonna | colonne[], { maxKeys? })</code></td><td>i record la cui chiave era già comparsa</td><td>sono zero</td></tr><tr><td><code>custom(nome, { init, step, verdict, threshold? })</code></td><td>ciò che restituisce <code>verdict</code></td><td><code>verdict</code> restituisce <code>ok: true</code></td></tr></tbody></table><p>Ogni check accetta <code>severity</code>: <code>"error"</code> (default) ferma la run, <code>"warn"</code> la lascia proseguire.</p><ul><li><strong>Soglie inclusive</strong>: <code>max: 0.05</code> accetta esattamente il 5 %.</li><li><strong>Null</strong> è <code>null</code>, <code>undefined</code> o chiave assente. La stringa vuota è un valore.</li><li><code>nullRatio</code> su <strong>zero record</strong> supera, con osservato <code>null</code>: che zero record siano un problema lo dice <code>rowCount</code>.</li><li><code>unique</code> <strong>ignora i record con la chiave null</strong>; con una chiave composta basta una colonna null. Riporta quanti duplicati ha visto, mai quali.</li><li><code>unique</code> ricorda le chiavi viste, in entrambe le modalità: ha un tetto di memoria proprio, <code>maxKeys</code> (default 100 000). Superarlo ferma la run anche se il check è <code>warn</code>: è un tetto di memoria, non un esito.</li><li><code>custom</code> è un reducer puro: niente IO, niente stato fuori da quello che <code>init</code> crea. L'osservato è un numero o un booleano, perché finisce nel report. <code>threshold</code> serve solo al report e al messaggio d'errore.</li><li><strong>I nomi dei check sono derivati</strong> (<code>rowCount</code>, <code>nullRatio(email)</code>, <code>unique(anno,numero)</code>); <code>custom</code> vuole un nome esplicito. Due check con lo stesso nome nello stesso <code>assert</code> fanno lanciare <code>assert()</code> alla costruzione.</li></ul><h3 id="gate-o-streaming" tabindex="-1">Gate o streaming <a class="header-anchor" href="#gate-o-streaming" aria-label="Permalink to "Gate o streaming""></a></h3><p><code>mode</code> decide quando escono i record.</p><ul><li><strong><code>"gate"</code> (default)</strong> trattiene tutti i record finché il verdetto non è noto, e li emette nello stesso ordine solo se nessun check <code>error</code> è fallito. Se fallisce, a valle non arriva niente. Costa memoria: fino a <code>maxRecords</code> record (default 100 000). Oltre il tetto la run si ferma con un <code>Error</code> semplice, che nessun <code>try-catch</code> assorbe, prima che a valle arrivi un record.</li><li><strong><code>"streaming"</code></strong> emette i record man mano e lancia dopo l'ultimo. Non trattiene niente, ma quando il verdetto arriva il caricamento a valle è già avvenuto.</li></ul><p><strong>La regola: streaming solo se il caricamento a valle è annullabile.</strong> Questa è la matrice, e vive solo qui:</p><table tabindex="0"><thead><tr><th>Caricamento a valle dell'<code>assert</code></th><th>Streaming protegge?</th><th>Perché</th></tr></thead><tbody><tr><td>Sink Postgres, SQL Server o MySQL <strong>senza</strong> <code>retry</code></td><td><strong>Sì</strong></td><td>l'errore annulla la transazione unica</td></tr><tr><td>Sink su uno <strong>staging</strong> seguito da un post-task di scambio</td><td><strong>Sì</strong></td><td>il post-task non parte: i dati rifiutati restano nello staging, la tabella in uso è intatta. Anche con <code>retry</code></td></tr><tr><td>Sink con una policy di <code>retry</code> o <code>rateLimit</code>, <strong>senza</strong> scambio</td><td>No</td><td>i blocchi già scritti sono confermati</td></tr><tr><td><code>arraySink</code>, sink di file e di cartella</td><td>No</td><td>le righe sono già scritte, e oggi non esiste un task di scambio per i file</td></tr><tr><td>Nodo <code>action</code> fra l'<code>assert</code> e il sink</td><td>No</td><td>gli effetti sono già avvenuti (mail spedita, chiamata fatta): uno scambio non li annulla</td></tr><tr><td>Qualunque sink dentro lo scope di un <code>try-catch</code></td><td>Non si costruisce, salvo lo scambio</td><td><code>validateGraph</code> rifiuta il grafo: il guard assorbirebbe il verdetto. Lo ammette solo con lo scambio, vedi sotto</td></tr></tbody></table><p>In gate nessuna riga è un problema: il sink non riceve niente finché il verdetto non è positivo.</p><p><strong>Streaming con lo scambio (write-then-swap).</strong> Il sink scrive su uno staging, e un <a href="./task">post-task</a> lo scambia con la tabella in uso solo se il sink è riuscito. Un verdetto negativo lo impedisce in entrambi i casi:</p><ul><li><strong>fuori da un guard</strong> la run fallisce, e il post-task non parte;</li><li><strong>dentro un guard</strong> il verdetto viene catturato e il sink scrive tutto, ma il suo input risulta <strong>troncato</strong>: il post-task è saltato e la run è <code>partial</code>. <code>validateGraph</code> ammette questa forma solo se <strong>ogni</strong> sink a valle dell'<code>assert</code> ha un edge di controllo verso un <code>task</code>, e a valle non c'è nessuna <code>action</code>.</li></ul><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">tryCatch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"guard"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"circuit-breaker"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
|
|
151
151
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"guard"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"qualita"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">assert</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"qualita"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"streaming"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, checks: [</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">unique</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)] }))</span></span>
|
|
152
152
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"qualita"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, staging) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// l'id del nodo è staging.name: "carica-staging"</span></span>
|
|
153
153
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"guard"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, errori, { fromPort: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"catch"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
|
package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js}
RENAMED
|
@@ -12,6 +12,6 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c
|
|
|
12
12
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --attendi</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # gate, build, push, CodePipeline</span></span></code></pre></div><p>L'immagine è la stessa di <code>image.yml</code> (o il Dockerfile del repo, se l'ha preso), con due tag su ECR: quello di deploy e quello di rilascio. La procedura completa, la <code>deploy-ecr.conf</code> e la creazione del servizio in <code>noeva-terraform</code> sono in <a href="./deploy-ecr">un cliente su ECR + ECS</a>.</p><h2 id="esecuzione" tabindex="-1">Esecuzione <a class="header-anchor" href="#esecuzione" aria-label="Permalink to "Esecuzione""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># una tantum: la tabella di destinazione deve esistere (DDL versionata nel repo cliente)</span></span>
|
|
13
13
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</span></span>
|
|
14
14
|
<span class="line"></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><blockquote><p><strong>Pipeline incrementali:</strong> senza <code>--workspace</code> lo stato di pipeline è un file in <code>ETL_STATE_DIR</code> (default <code>.state/</code>), e il filesystem di un container <code>--rm</code> si perde a ogni run: la pipeline ripartirebbe sempre da <code>initial</code>. Usare <code>run <pipeline> --workspace <id></code> (stato su <code>noeva-server-api</code>, lo stesso del worker), oppure montare un volume scrivibile dall'utente del container su <code>ETL_STATE_DIR</code>. Vedi <a href="./stato-incrementale">stato incrementale</a>.</p></blockquote><p>Variabili richieste: quelle della pipeline, elencate nella sua <a href="./../pipelines/README">scheda</a> e in <code>.env.example</code>, più quelle del core (<a href="./../conventions/variabili-del-core">Variabili d'ambiente del core</a>). In produzione iniettarle da un <strong>secret manager</strong> (AWS Secrets Manager / SSM), non da <code>.env</code>.</p><h2 id="modelli-di-deploy-per-cliente" tabindex="-1">Modelli di deploy per cliente <a class="header-anchor" href="#modelli-di-deploy-per-cliente" aria-label="Permalink to "Modelli di deploy per cliente""></a></h2><p>Il servizio gira tipicamente sull'<strong>infra del cliente</strong>. L'immagine abilita i primi tre modelli; PM2 gira dai sorgenti, senza immagine:</p><table tabindex="0"><thead><tr><th>Modello</th><th>Come</th><th>Note</th></tr></thead><tbody><tr><td><strong>Gestito da noi</strong></td><td>Un servizio ECS per cliente con <code>etl serve</code>, definito in Terraform</td><td>Il job parte dallo scheduler di Noeva</td></tr><tr><td><strong>ECS del cliente</strong></td><td>Stessa immagine, task definition nel loro account</td><td>Solo accesso al registry + secrets del cliente</td></tr><tr><td><strong>Docker locale del cliente</strong></td><td><code>docker run</code> schedulato da cron sul loro host</td><td>Più semplice; idempotenza rende sicuri retry/sovrapposizioni</td></tr><tr><td><strong>PM2 dai sorgenti</strong></td><td><code>ecosystem()</code> del pacchetto: <code>etl serve</code> dal repo, senza build</td><td>Per un server Windows senza Docker</td></tr></tbody></table><h2 id="scheduling" tabindex="-1">Scheduling <a class="header-anchor" href="#scheduling" aria-label="Permalink to "Scheduling""></a></h2><p>La pipeline è <strong>idempotente</strong> (upsert/MERGE su chiave naturale): rieseguire o sovrapporre run non duplica dati. Quindi lo scheduler può essere semplice:</p><ul><li><strong>cron</strong> che lancia <code>docker run ... run <pipeline></code>;</li><li><strong>ECS Scheduled Task</strong> (cron via EventBridge);</li><li>per dipendenze/backfill complessi in futuro → orchestratore (es. Temporal TS).</li></ul><h2 id="networking" tabindex="-1">Networking <a class="header-anchor" href="#networking" aria-label="Permalink to "Networking""></a></h2><p>Il container deve raggiungere <strong>sorgente e sink</strong> (PG
|
|
15
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><blockquote><p><strong>Pipeline incrementali:</strong> senza <code>--workspace</code> lo stato di pipeline è un file in <code>ETL_STATE_DIR</code> (default <code>.state/</code>), e il filesystem di un container <code>--rm</code> si perde a ogni run: la pipeline ripartirebbe sempre da <code>initial</code>. Usare <code>run <pipeline> --workspace <id></code> (stato su <code>noeva-server-api</code>, lo stesso del worker), oppure montare un volume scrivibile dall'utente del container su <code>ETL_STATE_DIR</code>. Vedi <a href="./stato-incrementale">stato incrementale</a>.</p></blockquote><p>Variabili richieste: quelle della pipeline, elencate nella sua <a href="./../pipelines/README">scheda</a> e in <code>.env.example</code>, più quelle del core (<a href="./../conventions/variabili-del-core">Variabili d'ambiente del core</a>). In produzione iniettarle da un <strong>secret manager</strong> (AWS Secrets Manager / SSM), non da <code>.env</code>.</p><h2 id="modelli-di-deploy-per-cliente" tabindex="-1">Modelli di deploy per cliente <a class="header-anchor" href="#modelli-di-deploy-per-cliente" aria-label="Permalink to "Modelli di deploy per cliente""></a></h2><p>Il servizio gira tipicamente sull'<strong>infra del cliente</strong>. L'immagine abilita i primi tre modelli; PM2 gira dai sorgenti, senza immagine:</p><table tabindex="0"><thead><tr><th>Modello</th><th>Come</th><th>Note</th></tr></thead><tbody><tr><td><strong>Gestito da noi</strong></td><td>Un servizio ECS per cliente con <code>etl serve</code>, definito in Terraform</td><td>Il job parte dallo scheduler di Noeva</td></tr><tr><td><strong>ECS del cliente</strong></td><td>Stessa immagine, task definition nel loro account</td><td>Solo accesso al registry + secrets del cliente</td></tr><tr><td><strong>Docker locale del cliente</strong></td><td><code>docker run</code> schedulato da cron sul loro host</td><td>Più semplice; idempotenza rende sicuri retry/sovrapposizioni</td></tr><tr><td><strong>PM2 dai sorgenti</strong></td><td><code>ecosystem()</code> del pacchetto: <code>etl serve</code> dal repo, senza build</td><td>Per un server Windows senza Docker</td></tr></tbody></table><h2 id="scheduling" tabindex="-1">Scheduling <a class="header-anchor" href="#scheduling" aria-label="Permalink to "Scheduling""></a></h2><p>La pipeline è <strong>idempotente</strong> (upsert/MERGE su chiave naturale): rieseguire o sovrapporre run non duplica dati. Quindi lo scheduler può essere semplice:</p><ul><li><strong>cron</strong> che lancia <code>docker run ... run <pipeline></code>;</li><li><strong>ECS Scheduled Task</strong> (cron via EventBridge);</li><li>per dipendenze/backfill complessi in futuro → orchestratore (es. Temporal TS).</li></ul><h2 id="networking" tabindex="-1">Networking <a class="header-anchor" href="#networking" aria-label="Permalink to "Networking""></a></h2><p>Il container deve raggiungere <strong>sorgente e sink</strong> (PG, SQL Server o MySQL), che possono stare su host/VPC diversi. In locale, dai container verso DB sull'host: usare <code>host.docker.internal</code> come <code>*HOST</code>. In cloud: curare security group / routing verso entrambi i DB.</p><h2 id="osservabilita-—-il-report-di-run-e-il-risultato" tabindex="-1">Osservabilità — il report di run è il risultato <a class="header-anchor" href="#osservabilita-—-il-report-di-run-e-il-risultato" aria-label="Permalink to "Osservabilità — il report di run è il risultato""></a></h2><p>Il servizio è <strong>stateless</strong>: emette un <strong>report</strong> e termina (niente DB lato servizio).</p><ul><li><strong><code>stdout</code></strong> = il report in JSON (un oggetto). <strong><code>stderr</code></strong> = log umani.</li><li><strong>exit code</strong>: <code>0</code> se <code>success</code>/<code>partial</code>, <code>≠0</code> se <code>failed</code> (utile per alerting dello scheduler).</li><li>Anche in errore viene emesso un report <code>status: "failed"</code>.</li></ul><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># cattura il report e i log separatamente</span></span>
|
|
16
16
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> report.json</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run.log</span></span>
|
|
17
17
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archivialo dove vuoi (è il chiamante a deciderlo): file, S3, CloudWatch, ...</span></span></code></pre></div><p>Schema completo e semantica: <a href="./../conventions/run-report">docs/conventions/run-report.md</a>.</p>`,37)])])}const g=e(l,[["render",t]]);export{c as __pageData,g as default};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import{_ as i,o as a,c as o,a5 as s}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Runbook: operazioni distruttive di excelSink","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/excel-operazioni-distruttive.md","filePath":"runbooks/excel-operazioni-distruttive.md"}'),n={name:"runbooks/excel-operazioni-distruttive.md"};function t(l,e,r,c,d,p){return a(),o("div",null,[...e[0]||(e[0]=[s(`<h1 id="runbook-operazioni-distruttive-di-excelsink" tabindex="-1">Runbook: operazioni distruttive di <code>excelSink</code> <a class="header-anchor" href="#runbook-operazioni-distruttive-di-excelsink" aria-label="Permalink to "Runbook: operazioni distruttive di \`excelSink\`""></a></h1><p>Cosa fanno <code>replace</code> e <code>cancellaQuando</code> sul workbook, come si dichiarano e <strong>come si torna indietro</strong>. 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.</p><blockquote><p><strong>Chi autorizza.</strong> Un nodo <code>excelSink</code> con <code>destructive: true</code> 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.</p></blockquote><h2 id="cosa-fanno" tabindex="-1">Cosa fanno <a class="header-anchor" href="#cosa-fanno" aria-label="Permalink to "Cosa fanno""></a></h2><table tabindex="0"><thead><tr><th>Opzione</th><th>Effetto sul foglio di destinazione</th></tr></thead><tbody><tr><td><code>mode: "replace"</code></td><td>Toglie <strong>tutte</strong> 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.</td></tr><tr><td><code>cancellaQuando</code> + <code>cancellaRighe: "rimuovi"</code> (default)</td><td>In <code>upsert</code>, il record che soddisfa la condizione <strong>toglie</strong> 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 <strong>prima di scrivere</strong>. Senza la riga, nessun effetto.</td></tr><tr><td><code>cancellaQuando</code> + <code>cancellaRighe: "svuota"</code></td><td>Come sopra ma la riga resta come <strong>buco</strong>: celle vuote, stile mantenuto, nessuna riga spostata, nessun riferimento toccato.</td></tr></tbody></table><p>Con <code>replace</code> 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.</p><h2 id="come-si-dichiara" tabindex="-1">Come si dichiara <a class="header-anchor" href="#come-si-dichiara" aria-label="Permalink to "Come si dichiara""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"replace"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> destructive: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"report.xlsx"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Dati"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
|
|
7
|
+
<span class="line"></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"upsert"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> key: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cancellaQuando: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"stato"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, equals: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"annullata"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cancellaRighe: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"rimuovi"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// o "svuota"; senza, vale "rimuovi"</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> destructive: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"note.xlsx"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"utente"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
16
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>destructive: true</code> è <strong>obbligatorio</strong>: senza, <code>excelSink</code> fa fallire la costruzione del grafo (<code>ConfigError</code>). Il flag compare nel descriptor del nodo (<code>destructive: true</code>), quindi nel DAG e nel report della run; con <code>cancellaQuando</code> compaiono anche il campo e <code>cancellaRighe</code>.</p><p>Se <code>"rimuovi"</code> 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 <code>cancellaRighe: "svuota"</code>. La tabella completa di ciò che si riscrive e di ciò che si rifiuta è nella <a href="./../connectors/excel">scheda del connettore</a>.</p><p><code>replace</code> <strong>non è <code>retrySafe</code></strong> (<code>retry</code> e <code>rateLimit</code> sul nodo fanno fallire <code>build()</code>); <code>upsert</code> con <code>cancellaQuando</code> resta <code>retrySafe</code>: svuotare due volte la stessa riga dà lo stesso foglio.</p><h2 id="prima-di-eseguire" tabindex="-1">Prima di eseguire <a class="header-anchor" href="#prima-di-eseguire" aria-label="Permalink to "Prima di eseguire""></a></h2><ol><li>Conferma percorso, foglio e storage nel descriptor del nodo: <code>replace</code> sul foglio sbagliato cancella il foglio sbagliato.</li><li><strong>Non c'è un backup automatico.</strong> Se il file conta, copialo prima nello stesso storage (<code>note.xlsx</code> → <code>note.xlsx.bak-AAAAMMGG</code>), oppure verifica che lo storage tenga le versioni.</li><li>Il file non deve essere aperto in Excel (<code>~$nome.xlsx</code>): il sink si ferma con un errore transitorio, ed è la risposta giusta.</li></ol><h2 id="come-tornare-indietro" tabindex="-1">Come tornare indietro <a class="header-anchor" href="#come-tornare-indietro" aria-label="Permalink to "Come tornare indietro""></a></h2><p>Il sink scrive con la <strong>sostituzione atomica</strong> dello storage: o c'è il file vecchio o c'è il nuovo, mai uno a metà. Per annullare una run:</p><ol><li><strong>Ferma la pipeline</strong>, così nessuna run riscrive sopra.</li><li><strong>Ripristina il file dallo storage</strong> (la copia fatta prima, o la versione precedente se lo storage le conserva) sul percorso di <code>path</code>.</li><li>Riesegui <strong>solo</strong> quando la causa è chiarita. Con <code>replace</code> la riesecuzione riscrive il foglio con il batch corrente; con <code>cancellaQuando</code> riapplica le cancellazioni ai record che arrivano.</li></ol><p>Le righe svuotate o tolte da <code>cancellaQuando</code> non si ricostruiscono dal file nuovo: i valori stanno solo nella copia precedente.</p><h2 id="quando-la-run-fallisce-a-meta" tabindex="-1">Quando la run fallisce a metà <a class="header-anchor" href="#quando-la-run-fallisce-a-meta" aria-label="Permalink to "Quando la run fallisce a metà""></a></h2><p>Il file non viene sostituito se il batch è invalido, se il foglio supera <code>maxSheetBytes</code>, 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.</p><h2 id="exceltask-cancellare-un-foglio-o-delle-colonne" tabindex="-1"><code>excelTask</code>: cancellare un foglio o delle colonne <a class="header-anchor" href="#exceltask-cancellare-un-foglio-o-delle-colonne" aria-label="Permalink to "\`excelTask\`: cancellare un foglio o delle colonne""></a></h2><p>Anche <code>excelTask</code> ha due operazioni che tolgono dati: <code>deleteSheet</code> e <code>deleteColumns</code>. Valgono le stesse regole: <code>destructive: true</code> sul task è <strong>obbligatorio</strong> (senza, la costruzione fallisce con <code>ConfigError</code>) e compare nel descriptor e nel report. Il task riscrive i riferimenti o <strong>rifiuta prima di scrivere</strong>, nominando quelli che si romperebbero (<code>#REF!</code>): 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.</p>`,21)])])}const k=i(n,[["render",t]]);export{u as __pageData,k as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as i,o as a,c as o,a5 as s}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Runbook: operazioni distruttive di excelSink","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/excel-operazioni-distruttive.md","filePath":"runbooks/excel-operazioni-distruttive.md"}'),n={name:"runbooks/excel-operazioni-distruttive.md"};function t(l,e,r,c,d,p){return a(),o("div",null,[...e[0]||(e[0]=[s("",21)])])}const k=i(n,[["render",t]]);export{u as __pageData,k as default};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as a,o as s,c as e,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: task SQL, truncate e scambio di tabelle","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/sql-task-truncate-swap.md","filePath":"runbooks/sql-task-truncate-swap.md"}'),t={name:"runbooks/sql-task-truncate-swap.md"};function l
|
|
1
|
+
import{_ as a,o as s,c as e,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: task SQL, truncate e scambio di tabelle","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/sql-task-truncate-swap.md","filePath":"runbooks/sql-task-truncate-swap.md"}'),t={name:"runbooks/sql-task-truncate-swap.md"};function o(l,i,r,d,p,h){return s(),e("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-task-sql-truncate-e-scambio-di-tabelle" tabindex="-1">Runbook: task SQL, truncate e scambio di tabelle <a class="header-anchor" href="#runbook-task-sql-truncate-e-scambio-di-tabelle" aria-label="Permalink to "Runbook: task SQL, truncate e scambio di tabelle""></a></h1><p>Come scrivere, verificare e rieseguire un caricamento <strong>write-then-swap</strong>: si carica uno staging e lo si scambia con la tabella in uso solo a caricamento riuscito. I pezzi sono il nodo <a href="./../nodes/task"><code>task</code></a> con <code>postgresSqlTask</code>, <code>mssqlSqlTask</code> o <code>mysqlSqlTask</code>, e gli edge di controllo.</p><blockquote><p><strong>Chi lo esegue.</strong> Chi possiede la pipeline (l'owner nella sua scheda) e chi è di turno quando una run fallisce. Un task con <code>destructive: true</code> cancella o sostituisce dati: leggi «Chi autorizza» prima della prima esecuzione in produzione.</p></blockquote><h2 id="la-forma" tabindex="-1">La forma <a class="header-anchor" href="#la-forma" aria-label="Permalink to "La forma""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ordini-swap"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Pre-task: lo staging parte vuoto. Ripetibile, quindi retrySafe.</span></span>
|
|
3
3
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
4
4
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "svuota-staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
@@ -26,11 +26,13 @@ import{_ as a,o as s,c as e,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
26
26
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "EXEC sp_rename 'dbo.ordini', 'ordini_swap'"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
27
27
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "EXEC sp_rename 'dbo.ordini_staging', 'ordini'"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
28
28
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "EXEC sp_rename 'dbo.ordini_swap', 'ordini_staging'"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
29
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">];</span></span></code></pre></div><ul><li><code>sp_rename</code> e <code>TRUNCATE TABLE</code> sono transazionali. <code>sp_rename</code> prende un lock <code>Sch-M</code> sulla tabella: aspetta le query in corso.</li><li>In alternativa, con due schemi: <code>ALTER SCHEMA staging_old TRANSFER dbo.ordini</code>, poi <code>ALTER SCHEMA dbo TRANSFER staging.ordini</code>. Ha senso quando si scambiano più tabelle insieme.</li><li><code>sp_rename</code> non aggiorna viste, stored procedure e funzioni che nominano la tabella: si risolvono per nome alla prossima esecuzione, quindi puntano alla tabella nuova. Una vista <code>WITH SCHEMABINDING</code> impedisce il rename.</li><li><code>TRUNCATE TABLE</code> fallisce su una tabella referenziata da una chiave esterna: lo staging non deve averne in ingresso.</li></ul><
|
|
29
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">];</span></span></code></pre></div><ul><li><code>sp_rename</code> e <code>TRUNCATE TABLE</code> sono transazionali. <code>sp_rename</code> prende un lock <code>Sch-M</code> sulla tabella: aspetta le query in corso.</li><li>In alternativa, con due schemi: <code>ALTER SCHEMA staging_old TRANSFER dbo.ordini</code>, poi <code>ALTER SCHEMA dbo TRANSFER staging.ordini</code>. Ha senso quando si scambiano più tabelle insieme.</li><li><code>sp_rename</code> non aggiorna viste, stored procedure e funzioni che nominano la tabella: si risolvono per nome alla prossima esecuzione, quindi puntano alla tabella nuova. Una vista <code>WITH SCHEMABINDING</code> impedisce il rename.</li><li><code>TRUNCATE TABLE</code> fallisce su una tabella referenziata da una chiave esterna: lo staging non deve averne in ingresso.</li></ul><h3 id="mysql-e-mariadb" tabindex="-1">MySQL e MariaDB <a class="header-anchor" href="#mysql-e-mariadb" aria-label="Permalink to "MySQL e MariaDB {#mysql-e-mariadb}""></a></h3><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> SWAP</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span></span>
|
|
30
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "RENAME TABLE dwh.ordini TO dwh.ordini_swap, dwh.ordini_staging TO dwh.ordini, dwh.ordini_swap TO dwh.ordini_staging"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">];</span></span></code></pre></div><ul><li><strong>Il DDL non è transazionale.</strong> <code>TRUNCATE</code>, <code>DROP</code>, <code>ALTER</code> e <code>RENAME TABLE</code> fanno un commit implicito: un errore dopo di loro non li annulla, e un task che li mescola a un DML non ha l'atomicità che ha su Postgres.</li><li><strong>Lo scambio atomico è uno statement solo</strong>: <code>RENAME TABLE</code> con più coppie rinomina tutto o niente, e chi legge vede la tabella vecchia o la nuova, mai una a metà. Per questo la lista ha una voce sola, non tre.</li><li><code>RENAME TABLE</code> aspetta un lock sui metadati della tabella: una transazione lunga che la sta leggendo lo ritarda, e le query nuove si mettono in coda dietro di lui. Conviene non averne in corso, o un <code>lock_wait_timeout</code> più corto sulla sessione.</li><li><code>TRUNCATE TABLE</code> fallisce su una tabella referenziata da una chiave esterna.</li><li>Indici, vincoli e permessi seguono la <strong>tabella</strong>, non il nome: le due tabelle devono avere la stessa struttura e gli stessi <code>GRANT</code>.</li></ul><h2 id="quando-lo-scambio-non-parte" tabindex="-1">Quando lo scambio non parte <a class="header-anchor" href="#quando-lo-scambio-non-parte" aria-label="Permalink to "Quando lo scambio non parte""></a></h2><p>Il post-task parte solo se il sink dello staging è <strong>riuscito</strong>. Non parte, e nel report risulta <code>skipped</code>, quando:</p><table tabindex="0"><thead><tr><th>Cosa è successo</th><th>Esito della run</th><th>Stato dei dati</th></tr></thead><tbody><tr><td>Il sink è fallito, o un altro nodo ha fatto fallire la run</td><td><code>failed</code></td><td>tabella in uso intatta, staging parziale o vuoto</td></tr><tr><td>Un controllo a monte è fallito dentro un <code>try-catch</code> (input «troncato»)</td><td><code>partial</code></td><td>tabella in uso intatta, staging con i dati rifiutati</td></tr><tr><td>Il pre-task è fallito</td><td><code>failed</code></td><td>tabella in uso intatta, staging com'era</td></tr><tr><td>La run è stata annullata</td><td><code>failed</code></td><td>tabella in uso intatta</td></tr></tbody></table><p>In tutti i casi la tabella in uso non è stata toccata.</p><p><strong>Attenzione agli scarti.</strong> I record finiti in dead-letter a monte, o rifiutati uno per uno da un guard <code>per-record</code>, <strong>non</strong> fermano lo scambio: sono un percorso previsto, e la run è <code>partial</code>. Un <code>assert</code> prima del sink vede solo i record che gli arrivano, non quelli già scartati. Se la regola è «nessuno scarto, altrimenti niente scambio», togli <code>deadLetter</code> e guard <code>per-record</code> a monte del sink dello staging: il primo record non valido fa fallire la run.</p><h2 id="verifica-dopo-un-fallimento-fra-caricamento-e-scambio" tabindex="-1">Verifica dopo un fallimento fra caricamento e scambio <a class="header-anchor" href="#verifica-dopo-un-fallimento-fra-caricamento-e-scambio" aria-label="Permalink to "Verifica dopo un fallimento fra caricamento e scambio""></a></h2><p>È il caso in cui lo staging è carico e lo scambio non è avvenuto, o non si sa.</p><ol><li><p><strong>Leggi il report</strong> (<code>etl runs show <runId></code>). Il nodo dello scambio ha uno di questi stati:</p><ul><li><code>skipped</code>: non è mai partito. La tabella in uso è quella di prima;</li><li>partito e <code>success: false</code>, con l'errore «la transazione è stata annullata»: lo scambio <strong>non</strong> è avvenuto. Vale anche per un annullamento a metà task;</li><li>partito e <code>success: false</code>, con l'errore «fallito durante il commit: l'esito è ignoto»: la connessione è caduta mentre il server confermava. Lo scambio può essere avvenuto: vai al passo 2. Questo errore non viene mai ritentato, nemmeno con <code>retrySafe</code>;</li><li>partito e <code>success: true</code>, con la run comunque <code>failed</code>: lo scambio <strong>è</strong> avvenuto, e a fallire è stato un nodo successivo (un <code>ANALYZE</code>, un altro ramo).</li></ul></li><li><p><strong>Verifica sul database</strong>, senza fidarti del solo report. Il caso ambiguo è una connessione caduta durante il commit: il task riporta un errore, ma il server può avere confermato.</p><div class="language-sql vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sql</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">-- PostgreSQL: quale tabella ha i dati di oggi?</span></span>
|
|
30
32
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">SELECT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'ordini'</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> AS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tabella, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">count</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">max</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(caricato_il) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">FROM</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dwh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ordini</span></span>
|
|
31
33
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">UNION ALL</span></span>
|
|
32
34
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">SELECT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'ordini_staging'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">count</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">max</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(caricato_il) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">FROM</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dwh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ordini_staging</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><p>Se esiste ancora una tabella <code>ordini_swap</code> la transazione non è stata annullata per intero: non deve succedere, fermati ed escala.</p></li><li><p><strong>Decidi</strong>: se la tabella in uso ha già i dati nuovi non c'è niente da fare. Altrimenti riesegui.</p></li></ol><h2 id="rieseguire" tabindex="-1">Rieseguire <a class="header-anchor" href="#rieseguire" aria-label="Permalink to "Rieseguire""></a></h2><p>Rieseguire l'intera run è sempre sicuro, a una condizione: <strong>lo scambio non deve essere già avvenuto</strong> (passo 2 sopra).</p><ul><li>Il pre-task svuota lo staging, quindi un caricamento parziale della run fallita non si somma.</li><li>Il sink dello staging è idempotente.</li><li>Se lo scambio era già avvenuto, una riesecuzione completa svuota lo staging, che ora contiene la <strong>versione precedente</strong>, e ricarica: il risultato è corretto, ma si perde la versione precedente. Non è un danno, è la perdita del paracadute.</li></ul><p><strong>Non ritentare lo scambio in automatico.</strong> Uno scambio a tre eseguito due volte riporta le tabelle com'erano: per questo non si dichiara <code>retrySafe</code>, e <code>retry</code> sul nodo farebbe fallire la costruzione del grafo. Un <code>TRUNCATE</code> o un <code>ANALYZE</code> sono ripetibili e possono dichiararlo.</p><h2 id="tornare-alla-versione-precedente" tabindex="-1">Tornare alla versione precedente <a class="header-anchor" href="#tornare-alla-versione-precedente" aria-label="Permalink to "Tornare alla versione precedente""></a></h2><p>Finché la run successiva non ha svuotato lo staging, la versione precedente è lì. Per tornare indietro si esegue lo stesso scambio a tre, a mano e in transazione:</p><div class="language-sql vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sql</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">BEGIN</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
33
35
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">ALTER</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> TABLE</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dwh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ordini</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RENAME </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">TO</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ordini_swap;</span></span>
|
|
34
36
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">ALTER</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> TABLE</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dwh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ordini_staging</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RENAME </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">TO</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ordini;</span></span>
|
|
35
37
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">ALTER</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> TABLE</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> dwh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ordini_swap</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RENAME </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">TO</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ordini_staging;</span></span>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">COMMIT</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><p>Va fatto <strong>prima</strong> della run successiva, e la schedulazione va sospesa finché non si è capito perché i dati nuovi erano sbagliati.</p><h2 id="chi-autorizza" tabindex="-1">Chi autorizza <a class="header-anchor" href="#chi-autorizza" aria-label="Permalink to "Chi autorizza""></a></h2><p>Un task <code>destructive</code> è un'operazione distruttiva: chiede <strong>conferma esplicita e un runbook</strong>. In pratica:</p><ul><li><strong>Prima esecuzione in produzione</strong> di una pipeline con un task distruttivo: la autorizza l'owner della pipeline, per iscritto sul ticket, dopo una run completa in un ambiente non di produzione. La scheda della pipeline elenca i task distruttivi e le tabelle che toccano.</li><li><strong>Un <code>TRUNCATE</code> sulla tabella in uso</strong> (non sullo staging) non è write-then-swap: fra il truncate e la fine del caricamento la tabella è vuota. Serve un'autorizzazione a parte, e di norma la risposta è usare lo scambio.</li><li><strong>Una modifica agli statement</strong> di un task distruttivo passa dalla review come ogni modifica al codice: nel DAG e nella PR lo statement è visibile, e <code>destructive: true</code> lo segnala.</li><li><strong>Un agente</strong> non esegue mai una pipeline contro un sistema di produzione senza una richiesta esplicita, e non lancia i test di integrazione dei task SQL fuori dai database locali: quei test si saltano da soli se l'host non è la macchina locale.</li></ul><h2 id="escalation" tabindex="-1">Escalation <a class="header-anchor" href="#escalation" aria-label="Permalink to "Escalation""></a></h2><ul><li>Primo livello: l'owner della pipeline, dalla sua scheda.</li><li>Secondo livello: chi amministra il database, se resta una tabella <code>*_swap</code> o un lock che non si libera.</li></ul>`,
|
|
38
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">COMMIT</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><p>Va fatto <strong>prima</strong> della run successiva, e la schedulazione va sospesa finché non si è capito perché i dati nuovi erano sbagliati.</p><h2 id="chi-autorizza" tabindex="-1">Chi autorizza <a class="header-anchor" href="#chi-autorizza" aria-label="Permalink to "Chi autorizza""></a></h2><p>Un task <code>destructive</code> è un'operazione distruttiva: chiede <strong>conferma esplicita e un runbook</strong>. In pratica:</p><ul><li><strong>Prima esecuzione in produzione</strong> di una pipeline con un task distruttivo: la autorizza l'owner della pipeline, per iscritto sul ticket, dopo una run completa in un ambiente non di produzione. La scheda della pipeline elenca i task distruttivi e le tabelle che toccano.</li><li><strong>Un <code>TRUNCATE</code> sulla tabella in uso</strong> (non sullo staging) non è write-then-swap: fra il truncate e la fine del caricamento la tabella è vuota. Serve un'autorizzazione a parte, e di norma la risposta è usare lo scambio.</li><li><strong>Una modifica agli statement</strong> di un task distruttivo passa dalla review come ogni modifica al codice: nel DAG e nella PR lo statement è visibile, e <code>destructive: true</code> lo segnala.</li><li><strong>Un agente</strong> non esegue mai una pipeline contro un sistema di produzione senza una richiesta esplicita, e non lancia i test di integrazione dei task SQL fuori dai database locali: quei test si saltano da soli se l'host non è la macchina locale.</li></ul><h2 id="escalation" tabindex="-1">Escalation <a class="header-anchor" href="#escalation" aria-label="Permalink to "Escalation""></a></h2><ul><li>Primo livello: l'owner della pipeline, dalla sua scheda.</li><li>Secondo livello: chi amministra il database, se resta una tabella <code>*_swap</code> o un lock che non si libera.</li></ul>`,41)])])}const u=a(t,[["render",o]]);export{k as __pageData,u as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as a,o as s,c as e,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: task SQL, truncate e scambio di tabelle","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/sql-task-truncate-swap.md","filePath":"runbooks/sql-task-truncate-swap.md"}'),t={name:"runbooks/sql-task-truncate-swap.md"};function l
|
|
1
|
+
import{_ as a,o as s,c as e,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: task SQL, truncate e scambio di tabelle","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/sql-task-truncate-swap.md","filePath":"runbooks/sql-task-truncate-swap.md"}'),t={name:"runbooks/sql-task-truncate-swap.md"};function o(l,i,r,d,p,h){return s(),e("div",null,[...i[0]||(i[0]=[n("",41)])])}const u=a(t,[["render",o]]);export{k as __pageData,u as default};
|