docs: define example database subproject and defer implementation
This commit is contained in:
Codex
@@ -0,0 +1,117 @@
|
||||
# Candidati Spider 2.0-DBT con documentazione di dominio
|
||||
|
||||
Ricerca del 27 settembre 2026. Obiettivo: scegliere un database locale complesso,
|
||||
con materiale da curare come Source Evidence di ThothII. Non vengono usate
|
||||
domande del benchmark, SQL attesi o punteggi come criterio di selezione.
|
||||
|
||||
## Raccomandazione
|
||||
|
||||
**Shopify è il candidato da verificare per primo**, perché combina commercio,
|
||||
pagamenti, rimborsi, inventario e ordini con documentazione dei significati e
|
||||
delle misure. Offre inoltre un dominio diverso dal Financial BIRD già proposto.
|
||||
QuickBooks è una valida alternativa se si preferisce la contabilità; Workday
|
||||
se si preferiscono personale e storia organizzativa. Questa priorità è una
|
||||
valutazione per il progetto, non una classificazione ufficiale Spider.
|
||||
|
||||
| Progetto Spider 2.0-DBT | Tabelle sorgente dichiarate | Coppie tabella/colonna descritte e distinte | Database locale indicato dal profilo |
|
||||
| --- | ---: | ---: | --- |
|
||||
| Shopify, `shopify001` | 34 | 578 | `shopify.duckdb` |
|
||||
| QuickBooks, `quickbooks001` | 40 | 426 | `quickbooks.duckdb` |
|
||||
| Workday, `workday001` | 21 | 436 | `workday.duckdb` |
|
||||
|
||||
Conteggi ricavati analizzando i rispettivi YAML `sources[].tables[]` e le
|
||||
descrizioni delle colonne; **non sono un'ispezione delle tabelle materializzate
|
||||
nei file DuckDB**. Alcune tabelle possono essere opzionali. Shopify ha 581
|
||||
dichiarazioni di colonna, ma tre sono duplicate: `order.total_shipping_price_set`,
|
||||
`order_line.tax_code`, `order_line_refund.subtotal_set`. I conteggi comprendono
|
||||
anche metadati tecnici e riferimenti `doc(...)`: **non equivalgono a un numero
|
||||
di Evidence Unit**. Sono esclusi i pacchetti di utilità generica dbt.
|
||||
Fonti: [Shopify schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml),
|
||||
[QuickBooks schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml),
|
||||
[Workday schema](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml).
|
||||
|
||||
## Shopify: commercio e operazioni
|
||||
|
||||
Lo schema documenta ordini e righe d'ordine, clienti, prodotti e varianti,
|
||||
transazioni, rimborsi, rettifiche, spedizioni, imposte, sconti, inventario,
|
||||
sedi e checkout abbandonati. Le descrizioni specificano sia la granularità
|
||||
delle entità sia il significato dei campi. Esempi di materiale semanticamente
|
||||
utile: il subtotale è dopo gli sconti e prima di spedizione, imposte e mance;
|
||||
`processed_at` è la data usata nei report analitici; l'ID API dell'ordine è
|
||||
distinto dal numero mostrato al cliente; valuta del negozio e valuta presentata
|
||||
al cliente hanno ruoli distinti. Le tre dichiarazioni duplicate richiedono
|
||||
normalizzazione prima dell'importazione documentale.
|
||||
[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/dbt_packages/shopify_source/models/src_shopify.yml).
|
||||
|
||||
Il progetto aggiunge definizioni di modelli analitici, inclusi ordini, coorti
|
||||
clienti e aggregazioni giornaliere del negozio; il solo `models/shopify.yml`
|
||||
ne dichiara 10. Sono modelli dbt, da tenere distinti dalle 34 sorgenti e dalle
|
||||
tabelle fisiche effettivamente disponibili. Queste definizioni sono un secondo
|
||||
livello di materiale per Evidence su granularità e metriche.
|
||||
[Modelli analitici](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/models/shopify.yml).
|
||||
|
||||
Il profilo indica esplicitamente DuckDB, percorso `./shopify.duckdb`, schema
|
||||
`main`. Non è necessario collegare un negozio Shopify reale per leggere il
|
||||
database distribuito dal progetto.
|
||||
[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/shopify001/profiles.yml).
|
||||
|
||||
## QuickBooks: contabilità e documenti commerciali
|
||||
|
||||
Le 40 sorgenti dichiarate coprono conti, clienti, fornitori, fatture e righe,
|
||||
pagamenti, depositi, acquisti, ordini, note di credito, trasferimenti e
|
||||
registrazioni contabili. Il dizionario definisce classificazioni dei conti e
|
||||
tipi delle righe fattura, distinguendo elementi di vendita, descrizione,
|
||||
sconto e subtotale.
|
||||
[Dizionario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/src_quickbooks.yml).
|
||||
|
||||
La documentazione del libro mastro contiene una regola esplicita utile come
|
||||
Evidence: l'importo aumenta il conto quando il tipo di movimento corrisponde
|
||||
al lato di incremento del conto, e lo diminuisce altrimenti. Definisce inoltre
|
||||
importi convertiti e saldi progressivi. `models/quickbooks.yml` dichiara 29
|
||||
modelli tra intermedi e analitici: non sono 29 ulteriori tabelle sorgente
|
||||
garantite. I due file di documentazione contengono complessivamente 120 blocchi
|
||||
`docs` (68 nel progetto, 52 nel pacchetto sorgente); anche qui sono definizioni
|
||||
da selezionare e curare, non 120 Evidence Unit già validate.
|
||||
[Modelli e regole contabili](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/quickbooks.yml),
|
||||
[glossario progetto](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/models/docs.md),
|
||||
[glossario sorgente](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/dbt_packages/quickbooks_source/models/docs.md).
|
||||
|
||||
Il profilo usa `./quickbooks.duckdb`.
|
||||
[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/quickbooks001/profiles.yml).
|
||||
|
||||
## Workday: personale, ruoli e storia organizzativa
|
||||
|
||||
Le sorgenti documentate comprendono lavoratori, posizioni, famiglie
|
||||
professionali, organizzazioni, assegnazioni e diverse tabelle storiche.
|
||||
Il glossario contiene 409 blocchi `docs`; molti sono definizioni brevi di
|
||||
attributi, non regole articolate. Fra i concetti documentati figurano FTE
|
||||
retribuito e lavorato, stato attivo/cessato, compensi, date di assunzione e
|
||||
appartenenze organizzative. La complessità temporale e organizzativa è
|
||||
interessante, ma il glossario da solo non giustifica chiamarlo il candidato
|
||||
con più Evidence di qualità.
|
||||
[Sorgenti](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/staging/src_workday.yml),
|
||||
[glossario](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/models/docs.md).
|
||||
|
||||
Il profilo usa `./workday.duckdb`.
|
||||
[Profilo](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/examples/workday001/profiles.yml).
|
||||
|
||||
## Download e prossimo controllo prima della scelta definitiva
|
||||
|
||||
Il README ufficiale fornisce due download Google Drive. Lo script di setup
|
||||
attende `DBT_start_db.zip` e `dbt_gold.zip`, estrae i file DuckDB e li distribuisce
|
||||
nei progetti e nella suite di riferimento. Per ThothII va scelto consapevolmente
|
||||
il contenuto da usare come esempio: non occorre importare il meccanismo di
|
||||
valutazione del benchmark. Questa ricerca verifica la pubblicazione del
|
||||
percorso di download e la configurazione locale; **non verifica il download
|
||||
integrale, dimensioni, righe, licenza dei singoli dati o schema fisico**.
|
||||
[README](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md),
|
||||
[setup ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/setup.py).
|
||||
|
||||
Prima di promettere il pacchetto di installazione occorre scaricare il
|
||||
candidato, confrontare tabelle e colonne reali con la documentazione,
|
||||
verificare copertura delle entità e consistenza dei dati, e scegliere quali
|
||||
definizioni diventino Source Evidence. Per PostgreSQL la conversione proposta
|
||||
è schema esplicito più dati esportati; CSV sarebbe un formato derivato.
|
||||
Vanno preservati tipi numerici, date, valute, valori nulli e contenuti
|
||||
strutturati eventualmente presenti, adattando le sole trasformazioni
|
||||
necessarie. Non è ancora stato implementato o testato alcun convertitore.
|
||||
Reference in New Issue
Block a user