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 schema wuic) e le route con md_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 in NlQuery:SensitiveColumns (forma route.colonna).
  • Blocco motivato: una richiesta su dati non esposti non restituisce niente e dice perche'.
CasoRisposta
dataset non nel catalogo dell'utente403 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 righe400 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 con extraProps.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}/ask risponde subito (messaggio dell'assistente pending); 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 (errori errors.nl_query.timeout, round_limit, token_budget, daily_budget).
  • Limiti per utente, controllati quando la domanda arriva: MaxPendingQuestionsPerUser domande in corso e MaxQuestionsPerMinutePerUser domande al minuto (429 errors.nl_query.too_many_pending e errors.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.

DoveChiaveEffetto
route (md_props_bag.nlQuery)excludedataset escluso dalle domande (anche se e' nel menu)
routeincludedataset curato: route non di sistema fuori dal menu resa interrogabile; i permessi restano quelli del motore (un grant di tabella negato la toglie comunque)
routedescription, synonymsdescrizione (max 500 caratteri) e sinonimi (max 10 da 60) mostrati al modello e usati nella ricerca dei dataset
routerowValuesfalse = 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)excludecolonna sensibile: mai selezionabile, filtrabile o raggruppabile
colonnadescription, synonymsdescrizione e sinonimi del campo per il modello
Snippet 1JSON
{ "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} e PUT 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) -> 400 errors.nl_query.config_invalid con args.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.

ChiaveDefaultSignificato
Enabledtruefunzione attiva
SendRowValuestruevalori delle righe inviati al modello (false = solo conteggi e aggregati)
MaxRows50righe massime di una query di righe
MaxGroups100gruppi massimi di un aggregato
MaxInValues50valori massimi in un filtro in
MaxFilterConditions20condizioni massime in un filtro
MaxAggregateSourceRows50000righe sorgente massime lette per un aggregato
MaxTextLength500lunghezza massima dei testi restituiti
SensitiveColumns[]colonne mai esposte, route.colonna
TimeZone"" (fuso del server)fuso per i periodi relativi (id di sistema)
Model / Effortclaude-opus-5-5 / lowmodello ed effort delle domande
LogRetentionDays90giorni di conservazione di sessioni e log
MaxToolRounds8giri di strumenti per domanda
MaxTokensPerCall16000max_tokens di ogni chiamata
QuestionTokenBudget400000token per domanda
DailyTokenBudgetPerUser3000000token per utente al giorno (letture dalla cache comprese)
MaxPendingQuestionsPerUser2domande in corso per utente (0 = nessun limite)
MaxQuestionsPerMinutePerUser10domande al minuto per utente (0 = nessun limite)
QuestionTimeoutSeconds120tempo massimo di una domanda
MaxDistinctValues50valori restituiti da distinct_values
HistoryTurns5domande precedenti date come contesto
UnverifiedModeflagcitazioni non verificate: flag (avviso) o table (solo fonti)
RefusalFallbackdefaultfallback lato server sui rifiuti del modello: default o none
ViewsEnabledtrueviste generate dalle domande
ViewPrefixnlv_prefisso degli oggetti delle viste generate ([a-z][a-z0-9_]{0,9})
Snippet 2JSON
{
  "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.

Snippet 3JSON
{
  "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": 10

Risposta (estratto): kind (rows | aggregate), columns, rows (per i lookup anche <campo>__text), matchedRows, totalGroups, truncated, measureColumns e la fonte citation con gridUrl:

Snippet 4JSON
{
  "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:

Snippet 5JSON
{
  "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 suo cite_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.

MetricaSogliaPrimo giroDopo le correzioni
risposte numeriche corrette (90 domande con risposta)>= 90%88/9090/90
citazione verificata e link "Apri in griglia" con le stesse righe>= 95%76/8284/84
rifiuti, "non so" e domande di chiarimento corretti (18)>= 90%18/1818/18
dati fuori perimetro o istruzioni nei dati eseguite000
  • 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 MaxAggregateSourceRows rifiutati; in non ammesso dentro un gruppo all annidato.
  • 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

Pagina /nl-query con il messaggio iniziale, i suggerimenti e la casella della domanda
Pagina /nl-query con il messaggio iniziale, i suggerimenti e la casella della domanda
Risposta a "Quanti ordini ha gestito ogni venditore a gennaio 2015?": tabella per venditore, citazione [1] e "Numeri verificati"
Risposta a "Quanti ordini ha gestito ogni venditore a gennaio 2015?": tabella per venditore, citazione [1] e "Numeri verificati"
Fonte aperta con "Mostra dati": grafico degli ordini per venditore e link "Apri in griglia"
Fonte aperta con "Mostra dati": grafico degli ordini per venditore e link "Apri in griglia"
Configurazione dell'amministratore: dataset curati o esclusi, descrizione per il modello, sinonimi e colonne sensibili
Configurazione dell'amministratore: dataset curati o esclusi, descrizione per il modello, sinonimi e colonne sensibili