Overview
Chiedi ai dati
"Chiedi ai dati" risponde a domande in linguaggio naturale sui dati dell'applicazione ("quanti ordini ha fatto ogni venditore a gennaio?") usando solo i dati che l'utente vede in griglia. Il modello non scrive mai SQL: compone un QueryPlan (un JSON ristretto) che il server valida con i permessi dell'utente e esegue con lo stesso motore della griglia. Ogni numero della risposta cita la sua fonte e si riapre in griglia con un clic.
Quando usarlo (use-case)
- Domande rapide sui numeri senza costruire un report: conteggi, totali, medie, andamenti per mese.
- Partire da una griglia filtrata e chiedere qualcosa su quelle righe ("di questi, quanti sono in ritardo?").
- Salvare la risposta come vista a menu (view builder o pivot) quando la domanda torna spesso.
- Usarlo dall'IDE: WUIC Assistant e Claude Code chiamano gli stessi strumenti con un token personale.
Chi puo' usarlo e quali dati vede
- Ogni utente autenticato. Ognuno interroga solo cio' che vede: stesse route, colonne, restrizioni di riga, azienda e filtri di default della griglia (le letture passano da
MetaService.getFlatRecordData). - Dataset = route non di sistema raggiungibili dal menu dell'utente, con almeno un campo esposto, piu' i dataset curati dall'amministratore (vedi "Configurazione dell'amministratore"). Non sono mai dataset le tabelle del framework (nome che inizia con
_o schemawuic) e le route conmd_props_bag{"nlQuery":{"exclude":true}}. - Campi esposti = colonne leggibili in griglia, tolte quelle con vista negata al ruolo, la denylist di sistema (per i non superadmin), le colonne con
mc_props_bag{"nlQuery":{"exclude":true}}e quelle elencate inNlQuery:SensitiveColumns(formaroute.colonna). - Blocco motivato: una richiesta su dati non esposti non restituisce niente e dice perche'.
| Caso | Risposta |
|---|---|
| dataset non nel catalogo dell'utente | 403 errors.nl_query.dataset_forbidden, args.dataset |
campo inesistente o non esposto (in select, filtro, raggruppamento, misura o ordinamento) | 403 errors.nl_query.columns_forbidden, args.dataset e args.columns |
| piano non valido (operatore, tipo del valore, profondita', limiti) | 400 errors.nl_query.invalid_plan, args.errors = [{ path, code, message }] |
| aggregato su troppe righe | 400 errors.nl_query.too_many_rows (restringere il filtro) |
funzione spenta (NlQuery:Enabled=false) | 403 errors.nl_query.disabled |
La pagina /nl-query e il pulsante in griglia
- Voce di menu "Chiedi ai dati" alla radice del menu (route
nl-query): la chat in variante domande sui dati; riprende l'ultima sessione dell'utente (le sessioni sono separate da quelle della chat sviluppatori). - Pulsante "Chiedi ai dati" nella toolbar della list-grid: apre
/nl-query?dataset=<route>&filterInfo=<filtro attivo>. La griglia diventa il contesto della domanda. Il server lo valida: il dataset deve essere nel catalogo dell'utente (altrimenti 403) e il filtro viene riscritto nel QueryPlan e validato; un filtro non valido si scarta e il dataset resta. Il pulsante non compare sulle route di sistema e si nasconde conextraProps.toolbar.hideAskData.
Risposte, fonti e "Apri in griglia"
- La risposta cita i numeri con
[n]: ogni[n]e' un risultato di uno strumento (righe, aggregato o record). Un controllo deterministico verifica che ogni numero citato compaia nella sua fonte; se non torna, il modello corregge una volta, poi la risposta esce con l'avviso "numeri non verificati" (NlQuery:UnverifiedMode=flag) oppure con le sole fonti (table). - Pannello fonti: descrizione leggibile del piano, righe coinvolte, "Mostra dati" (riesegue il piano con i permessi di chi guarda: tabella, e per gli aggregati un grafico; le righe non si salvano), "Apri in griglia":
/<route>/list?filterInfo=<filtro>, la griglia della route con lo stesso filtro (per un aggregato: le righe prima del raggruppamento, quindi lo stesso totale). - Grafico di un aggregato: a linee, ordinato per data, quando l'unico raggruppamento e' un periodo (giorno, mese, trimestre, anno); a barre negli altri casi, anche per una classifica di periodi ("i 5 mesi migliori"), dove una linea con i buchi ingannerebbe. Con piu' raggruppamenti l'etichetta e' composta ("Rossi Srl · 2026-01"). Le barre sono al massimo 20: oltre, il grafico mostra le prime 20 per valore della prima misura e lo dice ("prime 20 di 57"), la tabella le ha tutte. Una linea non si taglia (mancherebbe un pezzo di tempo); con piu' di 100 periodi il grafico non si disegna e una nota suggerisce un raggruppamento piu' ampio. Al massimo 3 serie, una per misura. "Nascondi grafico" toglie solo il grafico e lascia la tabella; "Nascondi dati" chiude entrambi.
Domande di chiarimento (ask_user)
Quando la domanda e' ambigua (quale cliente, quale periodo, quale dataset) il modello non indovina: chiude il turno con una domanda e da 2 a 6 opzioni costruite dai candidati reali. L'utente sceglie un pulsante (o scrive una risposta libera, se ammessa) e la scelta arriva come domanda successiva.
Turno asincrono e notifica
POST api/nl-query/sessions/{id}/askrisponde subito (messaggio dell'assistentepending); il turno gira in background con l'identita' e i permessi dell'utente che ha chiesto.- Durante il turno la pagina mostra il passo in corso ("eseguo la query su ..."); l'esito (risposta con le fonti, domanda di chiarimento o errore tipizzato) arriva sul messaggio e nella campanella, con il collegamento alla sessione (
/nl-query?sessionId=...&messageId=...): si puo' lasciare la pagina. - Limiti del turno:
QuestionTimeoutSeconds,MaxToolRounds,QuestionTokenBudget,DailyTokenBudgetPerUser(errorierrors.nl_query.timeout,round_limit,token_budget,daily_budget). - Limiti per utente, controllati quando la domanda arriva:
MaxPendingQuestionsPerUserdomande in corso eMaxQuestionsPerMinutePerUserdomande al minuto (429errors.nl_query.too_many_pendingeerrors.nl_query.rate_limited,args.max). Valgono per istanza del backend.
Viste generate dalle domande
Chiedendo esplicitamente di salvare i dati come vista ("crea una vista a menu con ...") il modello propone una vista invece di rispondere:
- kind `view` (view builder): elenco di righe o dettagli, anche con il testo dei campi collegati (lookup);
- kind `pivot` (pivot builder): totali, conteggi, raggruppamenti, serie per giorno/mese/anno;
- materializzata (
materialized: true,refresh=hourly|daily|weekly|monthly): tabella aggiornata da un job dello scheduler, per dati grandi o lenti.
La presentazione e' dichiarata nella proposta e validata dal server (columns[] con etichetta e, per i lookup, display = text | id | both; measures[] con l'etichetta di ogni misura del pivot; etichette tutte diverse): una proposta incoerente torna al modello con il motivo.
La proposta la vede chiunque; "Applica" e' solo del superadmin verificato sul DB (POST api/nl-query/sessions/{id}/messages/{messageId}/apply-view). Il server rivalida il piano con i permessi di chi applica, crea vista o pivot, la route in sola lettura (con il filtro del piano come filtro di default) e la voce di menu. Nome dell'oggetto: NlQuery:ViewPrefix + nome proposto (solo [a-z0-9_], max 60), mai sovrascritto (409 errors.nl_query.view_exists). Altri errori: views_disabled, view_forbidden, view_not_proposed, view_failed.
Richiesta all'amministratore. Quando la proposta arriva a un utente che non e' superadmin, a fine turno tutti i superadmin (ruolo superadmin verificato sul DB, utenti non cancellati) ricevono nella campanella la notifica "utente chiede la vista nome" (tipo nlq.view.review, testo nella lingua di chi legge). Il clic apre /nl-query?kind=view-review&sessionId=..&messageId=..: al posto della chat compaiono chi chiede, la domanda, la risposta e la proposta in sola lettura, con l'anteprima (rieseguita con i permessi del superadmin) e "Crea". Se chiede un superadmin nessuno viene avvisato: la vista la crea da se'. Non c'e' notifica di ritorno all'autore: la proposta sul suo messaggio mostra l'esito (vista creata e link alla voce di menu) quando riapre la sessione. API riservate al superadmin verificato sul DB (403 view_forbidden agli altri, 404 session_not_found se il messaggio non e' in quella sessione, 409 view_not_proposed senza proposta o se e' gia' applicata): GET api/nl-query/review/sessions/{id}/messages/{messageId} (lettura) e POST api/nl-query/review/sessions/{id}/messages/{messageId}/apply-view (stessa creazione di "Applica", con appliedBy = il superadmin; l'esito si salva sul messaggio dell'autore e la proposta si applica una volta sola).
Configurazione dell'amministratore (dataset curati, descrizioni, colonne sensibili)
Il superadmin configura "Chiedi ai dati" dalla pagina /nl-query con il pulsante "Configura" (dialog "Configurazione di Chiedi ai dati", visibile solo al superadmin verificato sul DB). La configurazione sta nella sezione nlQuery dei props bag dei metadati, quindi segue storico, confronto, pacchetti e promozioni del ciclo di vita dell'app; le altre chiavi del props bag restano intatte.
| Dove | Chiave | Effetto |
|---|---|---|
route (md_props_bag.nlQuery) | exclude | dataset escluso dalle domande (anche se e' nel menu) |
| route | include | dataset curato: route non di sistema fuori dal menu resa interrogabile; i permessi restano quelli del motore (un grant di tabella negato la toglie comunque) |
| route | description, synonyms | descrizione (max 500 caratteri) e sinonimi (max 10 da 60) mostrati al modello e usati nella ricerca dei dataset |
| route | rowValues | false = solo aggregati: al modello vanno conteggi e aggregati, le righe solo alla tabella sotto la risposta (vale il piu' restrittivo fra questo e NlQuery:SendRowValues) |
colonna (mc_props_bag.nlQuery) | exclude | colonna sensibile: mai selezionabile, filtrabile o raggruppabile |
| colonna | description, synonyms | descrizione e sinonimi del campo per il modello |
{ "nlQuery": { "include": true, "description": "Giacenze di magazzino per articolo", "synonyms": ["giacenze", "scorte"], "rowValues": false } }API (solo superadmin verificato, altrimenti 403 errors.nl_query.config_forbidden):
GET api/nl-query/admin/datasets: route configurabili (nel menu o no) con la loro configurazione e le impostazioni globali di appsettings in sola lettura;GET api/nl-query/admin/datasets/{route}ePUT api/nl-query/admin/datasets/{route}con{ "dataset": { ... }, "columns": [{ "name": "...", "exclude": true, ... }] }: scrive solo cio' che cambia, in transazione, poi invalida i metadati. Configurazione non valida (escluso e curato insieme, testi troppo lunghi) -> 400errors.nl_query.config_invalidconargs.reason; props bag non leggibile -> 409, mai sovrascritto.
Configurazione (sezione NlQuery di appsettings)
Tutte le chiavi sono facoltative: i default sono nel codice (Services/NlQuery/NlQueryOptions.cs). Provider, chiave e motore del modello non sono qui: sono quelli della chat RAG (rag-llm-provider, rag-llm-api-key). Con rag-llm-api-key = agent-sdk le domande passano dal CLI claude (credito della subscription): il CLI gira senza strumenti propri (niente shell, file o web), solo con il server MCP degli strumenti di sola lettura e senza i server MCP configurati per l'utente del processo; Model ed Effort gli vengono passati.
| Chiave | Default | Significato |
|---|---|---|
Enabled | true | funzione attiva |
SendRowValues | true | valori delle righe inviati al modello (false = solo conteggi e aggregati) |
MaxRows | 50 | righe massime di una query di righe |
MaxGroups | 100 | gruppi massimi di un aggregato |
MaxInValues | 50 | valori massimi in un filtro in |
MaxFilterConditions | 20 | condizioni massime in un filtro |
MaxAggregateSourceRows | 50000 | righe sorgente massime lette per un aggregato |
MaxTextLength | 500 | lunghezza massima dei testi restituiti |
SensitiveColumns | [] | colonne mai esposte, route.colonna |
TimeZone | "" (fuso del server) | fuso per i periodi relativi (id di sistema) |
Model / Effort | claude-opus-5-5 / low | modello ed effort delle domande |
LogRetentionDays | 90 | giorni di conservazione di sessioni e log |
MaxToolRounds | 8 | giri di strumenti per domanda |
MaxTokensPerCall | 16000 | max_tokens di ogni chiamata |
QuestionTokenBudget | 400000 | token per domanda |
DailyTokenBudgetPerUser | 3000000 | token per utente al giorno (letture dalla cache comprese) |
MaxPendingQuestionsPerUser | 2 | domande in corso per utente (0 = nessun limite) |
MaxQuestionsPerMinutePerUser | 10 | domande al minuto per utente (0 = nessun limite) |
QuestionTimeoutSeconds | 120 | tempo massimo di una domanda |
MaxDistinctValues | 50 | valori restituiti da distinct_values |
HistoryTurns | 5 | domande precedenti date come contesto |
UnverifiedMode | flag | citazioni non verificate: flag (avviso) o table (solo fonti) |
RefusalFallback | default | fallback lato server sui rifiuti del modello: default o none |
ViewsEnabled | true | viste generate dalle domande |
ViewPrefix | nlv_ | prefisso degli oggetti delle viste generate ([a-z][a-z0-9_]{0,9}) |
{
"NlQuery": {
"SendRowValues": false,
"SensitiveColumns": ["customers.CreditLimit"],
"TimeZone": "Europe/Rome"
}
}API deterministica (senza modello)
Con la sessione dell'utente (cookie k-user), per integrazioni e test: nessuna chiamata al modello.
GET api/nl-query/datasets?q=<testo>: catalogo dell'utente (key,label,description,menuPath).GET api/nl-query/datasets/{dataset}: campi esposti (name,label,kind=Text|Number|Date|DateTime|Bool|Lookup|Dictionary,isKey,lookupRoute, voci dei dizionari).POST api/nl-query/plan/execute: esegue un QueryPlan (corpo JSON).
QueryPlan: dataset, select (solo righe), filter ({field, op, value} o gruppi {all:[...]} / {any:[...]}, massimo due livelli), groupBy (massimo 3, {field, bucket: day|month|quarter|year} sulle date), measures (count|sum|avg|min|max, count anche senza campo), sort (by = campo, raggruppamento o nome della misura), limit. Operatori: eq, neq, gt, gte, lt, lte, contains, startswith, endswith, in, between, period (today, this_month, last_30_days, this_year, ...), isnull, notnull, ammessi secondo il tipo del campo. Proprieta' sconosciute = errore con il loro path.
{
"dataset": "orders",
"filter": { "field": "OrderDate", "op": "between", "value": ["2015-01-01", "2015-01-31"] },
"groupBy": ["SalespersonPersonID"],
"measures": [{ "fn": "count", "as": "ordini" }],
"sort": [{ "by": "ordini", "dir": "desc" }],
"limit": 10Risposta (estratto): kind (rows | aggregate), columns, rows (per i lookup anche <campo>__text), matchedRows, totalGroups, truncated, measureColumns e la fonte citation con gridUrl:
{
"ok": true,
"result": {
"kind": "aggregate",
"dataset": "orders",
"rows": [{ "SalespersonPersonID": 8, "SalespersonPersonID__text": "...", "ordini": 213 }],
"matchedRows": 1830,Da WUIC Assistant e Claude Code (token personale)
Gli stessi strumenti, le stesse istruzioni e gli stessi controlli della chat dell'app, letti dal backend: nessun client ne tiene una copia.
1. apiTokensEnabled=true (vedi AppSettings).
2. Menu utente, voce "Token API": nuovo token con la casella "Domande sui dati (WUIC Assistant)" (scope nl-query). Il token (wuic_pat_...) si vede una volta sola.
3. In WUIC Assistant: comando "WUIC Assistant: Imposta token API WUIC". In Claude Code (o un altro client MCP): variabile WUIC_API_TOKEN nell'env del server wuic-rag di .mcp.json:
{
"mcpServers": {
"wuic-rag": {
"command": "node",
"args": ["scripts/mcp/wuic-rag-mcp.mjs"],
"env": {
"WUIC_BACKEND": "http://localhost:5000",Il server MCP apre una conversazione (POST api/nl-query/tools/session, solo con Authorization: Bearer; il cookie qui non conta) e aggiunge gli strumenti nlq_*:
nlq_instructions: regole e flusso di lavoro dal backend, da leggere per prime;nlq_list_datasets,nlq_describe_dataset,nlq_distinct_values,nlq_query_rows,nlq_aggregate,nlq_get_record: letture con i permessi del proprietario del token, ognuna con il suocite_id;nlq_nl_verify_answer: controllo delle citazioni della risposta prima di darla all'utente;nlq_ask_user: valida la domanda di chiarimento, che il client pone con il suo meccanismo;nlq_propose_view: proposta di vista (nessuna scrittura);- azione `nlq_apply_view` (
annotations.destructiveHint, descrizione "[Requires explicit user approval]"): crea la vista proposta con lo stesso input, solo dopo l'approvazione esplicita dell'utente e solo se il proprietario del token e' superadmin.
Errori: token senza scope nl-query -> 403 errors.auth.api_token_scope; token revocato, scaduto o funzione spenta -> 401 subito, anche a conversazione aperta. La conversazione dura 60 minuti e il server MCP ne riapre un'altra da solo.
Accuratezza misurata (eval)
Eval con il modello del piano (Claude Opus 5.5, claude-opus-5-5, effort low, motore agent-sdk) su 108 domande sui dati di WideWorldImporters (23/10/2026). Le risposte attese sono calcolate con SQL scritto a mano, con le restrizioni dell'utente scritte esplicitamente; le domande sono fatte da tre utenti con permessi diversi.
| Metrica | Soglia | Primo giro | Dopo le correzioni |
|---|---|---|---|
| risposte numeriche corrette (90 domande con risposta) | >= 90% | 88/90 | 90/90 |
| citazione verificata e link "Apri in griglia" con le stesse righe | >= 95% | 76/82 | 84/84 |
| rifiuti, "non so" e domande di chiarimento corretti (18) | >= 90% | 18/18 | 18/18 |
| dati fuori perimetro o istruzioni nei dati eseguite | 0 | 0 | 0 |
- Categorie: conteggi e somme, filtri e periodi, raggruppamenti, top-N, confronti fra periodi, ricerche di record, permessi (righe, route e colonne negate, tabelle di sistema, password), configurazione dell'amministratore (dataset curato, solo aggregati, colonne sensibili, dataset escluso), istruzioni malevole nei dati, domande senza risposta o ambigue, domande in inglese, francese, tedesco e spagnolo.
- "Dopo le correzioni" = rigiro dei soli casi falliti dopo aver corretto il controllo delle citazioni e il prompt.
- Latenza: mediana 16 s, 95° percentile 37 s. Costo: circa 0,08 USD a domanda a prezzi di listino.
Limiti
- Verificato con test su database su SQL Server, MySQL, PostgreSQL e Oracle (catalogo, operatori, periodi relativi, aggregati, viste generate).
- Aggregati oltre
MaxAggregateSourceRowsrifiutati;innon ammesso dentro un gruppoallannidato. - Senza licenza (Trial) il motore legge al massimo 20 righe: le domande su al massimo 20 righe rispondono normalmente, oltre la risposta e' rifiutata (
errors.nl_query.license_limited) perche' non sarebbe completa. - Viste generate (righe, materializzate, pivot) su tutti e quattro i DBMS; filtro della vista solo in AND.
- Periodi relativi calcolati nel fuso
TimeZone(o del server) e fissati al momento dell'applicazione di una vista.
Screenshot

![Risposta a "Quanti ordini ha gestito ogni venditore a gennaio 2015?": tabella per venditore, citazione [1] e "Numeri verificati"](https://wuic-framework.com/assets/wuic-framework-docs/screenshots/manual__nl-query__02.png)

