# NL Query — Pattern e convenzioni
**Versione:** 1.0
**Aggiornato:** 2026-06-08

Questo documento accumula le scelte interpretative emerse dalle domande reali.
Ogni pattern è la risposta alla domanda: "quando l'utente dice X, io intendo Y".

---

## Termini di dominio

| Termine utente | Interpretazione SQL | Note |
|---|---|---|
| "film italiano" | `p.tipologia = 'FILM' AND (p.paesi_produzione1 = 'I' OR p.paesi_produzione2 = 'I' OR p.paesi_produzione3 = 'I')` | Include co-produzioni con Italia in qualsiasi posizione |
| "prime time" | `e.fascia = 'PR'` | Fascia PR in emesso — non usare ora_inizio |
| "ultimi N anni" | `e.data_emissione >= date('now', '-N years')` oppure stringa ISO calcolata | data_emissione è VARCHAR — confronto stringa ISO |
| "C5" / "Canale 5" | `e.rete = 'C5'` | |
| "trasmesso" | emesso — tutte le TX, non solo prima visione | Se l'utente vuole solo PV aggiunge "prima visione" |
| "diritti in scadenza nel YYYY" | CTE primary_contract: prendi contratto attivo oggi (priority=1) o ultimo scaduto (priority=2, scad DESC). Filtra YEAR(scad)=YYYY sul primario. Esclude film già rinnovati con contratto attivo diverso. | NON usare semplice YEAR(scad)=YYYY su tutti i contratti — includerebbe film già rinnovati |
| "una riga per film con contratti aggregati" | GROUP BY (prodotto, edizione) + STRING_AGG(DISTINCT distributori) + MAX(scad) AS scadenza | Usare MAX(scad) come data di scadenza — una sola colonna SCADENZA |
| RIFER nei diritti | Usare `CAST(p.prodotto AS VARCHAR) AS rifer` — il Linker usa prodotto (int), non program_id. Includere anche `p.program_id` come colonna separata. | program_id è il codice OnAir ma i diritti join su prodotto |

---

## Convenzioni di output

- **Formato file:** CSV con separatore `;`, encoding UTF-8-sig (BOM per compatibilità Excel)
- **Intestazioni:** MAIUSCOLO, underscore al posto degli spazi
- **Percorso output:** `datawarehouse/` con nome descrittivo (es. `film_italiani_primetime_C5_5anni.csv`)
- **Sidecar SQL:** per ogni CSV produrre anche `<stesso_nome>.sql` con domanda, data, nome output e query completa
- **Ordinamento default:** per data decrescente (più recente prima)
- **Deduplicazione:** GROUP BY `(prodotto, edizione)` per avere titoli distinti, non singole TX
- **Codice OnAir:** includere sempre `p.program_id AS rifer` come prima colonna in tutte le estrazioni che coinvolgono prodotti. Colonna sempre chiamata `rifer`.

---

## Path parquet (produzione)

```
I:/SOFTWARE/PYTHON_SRV/PYTHON_LOCAL/MyICR_Suite/local_db/parquet/
  prodotti.parquet
  emesso.parquet
  diritti.parquet
  imdb.parquet
  imdb_full.parquet
  cast.parquet
  gemma.parquet
  osservatorio.parquet
  boxoffice.parquet
  scelte_rete.parquet
```

DB SQLite:
```
I:/SOFTWARE/PYTHON_SRV/sync_db/linker.db          — OTT_EXT, LINKER_REPOSITORY, LINKER_VALUTAZIONE, COMPETITIVE_IMDB_MAP
I:/SOFTWARE/PYTHON_SRV/sync_db/mediatrack.db       — AnagraficaMedia, LogAggiornamenti, OmdbData
I:/SOFTWARE/PYTHON_SRV/PYTHON_LOCAL/MyICR_Suite/local_db/ott.db  — OTT
```

---

## Gotcha attivi (emersi da query reali)

| # | Gotcha | Come gestirlo |
|---|--------|---------------|
| 1 | `emesso.data_emissione` è VARCHAR | Confronti con stringhe ISO `'YYYY-MM-DD'` |
| 2 | "film italiano" include co-produzioni | Controllare paesi_produzione1/2/3 |
| 3 | `ora_inizio` è in formato HHMMSS (intero) — non secondi | Per prime time usare `fascia = 'PR'`, non ora_inizio |

---

## Domande eseguite

| # | Domanda | File output | Note |
|---|---------|-------------|------|
| 1 | Film italiani trasmessi da C5 in prime time negli ultimi 5 anni | `film_italiani_primetime_C5_5anni_v2.csv` | 85 titoli distinti |
| 2 | Film con diritti in scadenza nel 2026 | `film_diritti_scadenza_2026_v4.csv` | 486 film; contratto primario (attivo oggi o ultimo scaduto); esclude già rinnovati |
| 3 | Film di Alberto Sordi con diritti in essere | `film_alberto_sordi_diritti_attivi.csv` | 62 righe (include edizioni); scad=9999-12-31 = perpetui; ⚠ DI CHE SEGNO SEI? scade 30/06/2026 |