docs: define example database subproject and defer implementation
This commit is contained in:
Codex
@@ -0,0 +1,49 @@
|
||||
# Dimensioni dei sei database candidati
|
||||
|
||||
Verifica del 27 settembre 2026 tramite lettura HTTP Range della directory centrale
|
||||
degli archivi ZIP ufficiali. I valori sono le dimensioni non compresse dichiarate
|
||||
per i singoli file, non il consumo misurato dopo importazione in PostgreSQL.
|
||||
GB e MB sono decimali: 1 GB = 1.000.000.000 byte.
|
||||
|
||||
| Database | Formato | Byte | GB | MB |
|
||||
| --- | --- | ---: | ---: | ---: |
|
||||
| Financial, BIRD Mini-Dev | SQLite | 71.294.976 | 0,071295 | 71,295 |
|
||||
| European Football, BIRD Mini-Dev | SQLite | 597.754.880 | 0,597755 | 597,755 |
|
||||
| F1, Spider 2.0-Lite | SQLite | 74.940.416 | 0,074940 | 74,940 |
|
||||
| Shopify, Spider 2.0-DBT, shopify001 | DuckDB iniziale | 19.935.232 | 0,019935 | 19,935 |
|
||||
| QuickBooks, Spider 2.0-DBT, quickbooks001 | DuckDB iniziale | 50.606.080 | 0,050606 | 50,606 |
|
||||
| Workday, Spider 2.0-DBT, workday001 | DuckDB iniziale | 28.323.840 | 0,028324 | 28,324 |
|
||||
| Totale | | 842.855.424 | 0,842855 | 842,855 |
|
||||
|
||||
## Provenienza
|
||||
|
||||
- [BIRD Mini-Dev ZIP](https://bird-bench.oss-cn-beijing.aliyuncs.com/minidev.zip),
|
||||
collegato dal [repository ufficiale](https://github.com/bird-bench/mini_dev).
|
||||
Archivio: 800.943.648 byte; Last-Modified 20 giugno 2024.
|
||||
Entry: `minidev/MINIDEV/dev_databases/financial/financial.sqlite` e
|
||||
`minidev/MINIDEV/dev_databases/european_football_2/european_football_2.sqlite`.
|
||||
- [Spider database locali](https://drive.google.com/file/d/1coEVsCZq-Xvj9p2TnhBFoFTsY-UoYGmG/view),
|
||||
collegati dal [README Lite](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md).
|
||||
Archivio: 456.643.204 byte; entry `f1.sqlite`.
|
||||
- [DBT_start_db.zip](https://drive.google.com/file/d/1N3f7BSWC4foj-V-1C9n8M2XmgV7FOcqL/view),
|
||||
collegato dal [README DBT](https://github.com/xlang-ai/Spider2/blob/main/spider2-dbt/README.md).
|
||||
Archivio: 377.819.033 byte; Last-Modified 19 dicembre 2024.
|
||||
Entry: `shopify001/shopify.duckdb`, `quickbooks001/quickbooks.duckdb`,
|
||||
`workday001/workday.duckdb`.
|
||||
|
||||
I pesi degli archivi completi non sono quelli dei soli database selezionati:
|
||||
contengono anche altri esempi. Non sommarli alla tabella salvo voler conservare
|
||||
localmente tutti i pacchetti originali.
|
||||
|
||||
Per confronto, l'archivio ufficiale `dbt_gold.zip` contiene file corrispondenti di
|
||||
22.032.384 byte (Shopify), 54.013.952 byte (QuickBooks) e 28.848.128 byte (Workday).
|
||||
Sono versioni di risultato del benchmark, non la base scelta per la tabella e non
|
||||
una previsione del consumo finale di ThothII.
|
||||
|
||||
## Limiti
|
||||
|
||||
Il totale esclude descrizioni, Evidence, CSV esportati, indici aggiuntivi, log,
|
||||
PostgreSQL, Qdrant, immagini Docker e modelli locali. La conversione può modificare
|
||||
sensibilmente l'occupazione. Non sono state estratte tutte le tabelle né contate
|
||||
le righe: il peso del file non prova che tutte le tabelle documentate siano popolate.
|
||||
La complessità di schema e dominio non implica grandi volumi nei dati dimostrativi.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Alternative Spider 2.0-Lite per database dimostrativi con Evidence
|
||||
|
||||
Verifica del 27 settembre 2026. Il criterio è complessità del database e qualità
|
||||
della documentazione di dominio da curare in ThothII, non prestazioni sul benchmark
|
||||
né numero di domande pubblicate. Nessun database è stato installato.
|
||||
|
||||
## Metodo e limiti
|
||||
|
||||
Ispezionati DDL, metadati per tabella e documenti ufficiali in
|
||||
[Spider2](https://github.com/xlang-ai/Spider2), revisione osservata
|
||||
`cafb867313aab4e674652054198f383cf4018943`. I conteggi sotto sono delle tabelle
|
||||
dichiarate nei DDL e delle colonne nei JSON, non un'ispezione dei file SQLite.
|
||||
La [procedura ufficiale](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/README.md)
|
||||
offre un archivio dei database locali. I database cloud seguono un percorso diverso.
|
||||
|
||||
## Candidati locali
|
||||
|
||||
| Database | Tabelle / colonne nei metadati | Materiale semantico riscontrato | Valutazione |
|
||||
| --- | --- | --- | --- |
|
||||
| `E_commerce` | 11 / 70 | Documento RFM; documentazione originale Olist da integrare | Il più coerente dei candidati Lite esaminati per una demo aziendale, ma complessità media |
|
||||
| `complex_oracle` | 10 / 140 | Proiezione vendite e conversioni valutarie; dizionario originale Oracle SH da confrontare | Buon caso analitico, meno esteso relazionalmente |
|
||||
| `oracle_sql` | 38 / 124 | Documento sul rapporto vendite/media mobile e finestre temporali | Molte tabelle, documentazione semantica allegata troppo parziale |
|
||||
| `AdventureWorks` | 13 / 120 | Documentazione originale Microsoft, da riallineare al sottoinsieme Spider | Non confondere questo estratto con l'intero AdventureWorks |
|
||||
|
||||
Conteggi ricavati dai DDL e JSON ufficiali: [E_commerce](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/E_commerce),
|
||||
[complex_oracle](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/complex_oracle),
|
||||
[oracle_sql](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/oracle_sql),
|
||||
[AdventureWorks](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/sqlite/AdventureWorks).
|
||||
In tutti i JSON di questi quattro candidati, gli array `description` controllati
|
||||
sono vuoti: tipi e righe di esempio non costituiscono da soli un dizionario di dominio.
|
||||
|
||||
### E_commerce
|
||||
|
||||
Comprende ordini, righe d'ordine, pagamenti, recensioni, prodotti, clienti, venditori,
|
||||
geolocalizzazione e lead. Il [documento RFM](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/RFM.md)
|
||||
definisce recency, frequency, monetary e undici segmenti con regole di assegnazione.
|
||||
Sono fonti concrete di formule e regole, da rivedere e collegare allo schema.
|
||||
|
||||
La [fonte originale Olist](https://www.kaggle.com/olistbr/brazilian-ecommerce/metadata)
|
||||
fornisce CSV e spiega una distinzione utile: `customer_id` identifica il cliente
|
||||
nel contesto dell'ordine, mentre `customer_unique_id` permette di riconoscere acquisti
|
||||
ripetuti della stessa persona. La distribuzione Olist di base contiene nove file;
|
||||
non equivale automaticamente alle undici tabelle Spider, che includono i lead.
|
||||
|
||||
### complex_oracle
|
||||
|
||||
Il [documento allegato](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/projection_calculation.md)
|
||||
descrive proiezione mensile delle vendite, crescita rispetto all'anno precedente,
|
||||
conversione in USD e gestione di cambi mancanti. Lo schema ha vendite e costi con
|
||||
dimensioni prodotto, cliente, calendario, canale, promozione e geografia.
|
||||
|
||||
Nomi e struttura sono riconducibili al [Sales History di Oracle](https://github.com/oracle-samples/db-sample-schemas/tree/main/sales_history).
|
||||
Il suo script `sh_create.sql` contiene 88 commenti `COMMENT ON TABLE/COLUMN` e la
|
||||
distribuzione comprende CSV. È materiale aggiuntivo utile, ma ogni corrispondenza
|
||||
con lo schema Spider, incluse estensioni come `currency`, va verificata: non si
|
||||
deve importare la documentazione dell'originale come se descrivesse automaticamente
|
||||
ogni adattamento Spider.
|
||||
|
||||
### oracle_sql
|
||||
|
||||
Le tabelle coprono magazzino, ordini, confezioni annidate, vendite mensili e altri
|
||||
sottodomini eterogenei. Il [documento di calcolo](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/calculation_method.md)
|
||||
tratta tre aspetti: rapporto fra vendite e media mobile centrata, finestre di dodici
|
||||
mesi e limiti temporali per evitare effetti ai bordi. Questo non documenta in modo
|
||||
completo le altre parti del database: sconsigliato come scelta basata sulla sola
|
||||
abbondanza di tabelle.
|
||||
|
||||
## Alternativa cloud con documentazione più ricca
|
||||
|
||||
`ga4` offre tre documenti complementari: [dizionario degli eventi](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_obfuscated_sample_ecommerce.events.md),
|
||||
[dimensioni e metriche](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_dimensions_and_metrics.md)
|
||||
e [categorie delle pagine](https://github.com/xlang-ai/Spider2/blob/main/spider2-lite/resource/documents/ga4_page_category.md).
|
||||
Coprono campi annidati, classificazione dei canali e regole di interpretazione;
|
||||
sono più vicini al requisito semantico. Tuttavia la
|
||||
[distribuzione Spider è BigQuery](https://github.com/xlang-ai/Spider2/tree/main/spider2-lite/resource/databases/bigquery/ga4):
|
||||
molte tabelle sono partizioni giornaliere dello stesso schema logico. Il conteggio
|
||||
fisico non è una misura utile di complessità relazionale. Esportazione locale e
|
||||
adattamento PostgreSQL sarebbero lavoro aggiuntivo, non un semplice import SQLite.
|
||||
|
||||
## Esito
|
||||
|
||||
Nessuno dei quattro candidati SQLite esaminati combina da solo schema molto esteso
|
||||
e documentazione di dominio completa già pronta. Per cercare una scelta più forte,
|
||||
confrontare con i progetti Spider 2.0-DBT nella ricerca separata
|
||||
`2026-09-27-spider2-dbt-evidence-candidates.md`. I modelli documentati di dbt non
|
||||
vanno confusi con tabelle fisiche già presenti, né le librerie di utility con Evidence.
|
||||
Reference in New Issue
Block a user