Overview
Ask your data
"Ask your data" answers natural-language questions about the application data ("how many orders did each salesperson take in January?") using only the data the user can see in the grid. The model never writes SQL: it builds a QueryPlan (a restricted JSON) that the server validates with the user's permissions and runs with the same engine as the grid. Every number in the answer cites its source and reopens in the grid with one click.
When to use it (use cases)
- Quick questions about numbers without building a report: counts, totals, averages, monthly trends.
- Start from a filtered grid and ask something about those rows ("of these, how many are late?").
- Save the answer as a menu view (view builder or pivot) when the question comes back often.
- Use it from the IDE: WUIC Assistant and Claude Code call the same tools with a personal token.
Who can use it and which data it sees
- Every authenticated user. Each user queries only what they see: same routes, columns, row restrictions, company and default filters as the grid (reads go through
MetaService.getFlatRecordData). - Datasets = non-system routes reachable from the user's menu, with at least one exposed field, plus the datasets curated by the administrator (see "Administrator configuration"). Framework tables (name starting with
_or schemawuic) and routes withmd_props_bag{"nlQuery":{"exclude":true}}are never datasets. - Exposed fields = columns readable in the grid, minus those with view denied to the role, the system denylist (for non-superadmins), columns with
mc_props_bag{"nlQuery":{"exclude":true}}and those listed inNlQuery:SensitiveColumns(formroute.column). - Blocked with a reason: a request on data that is not exposed returns nothing and says why.
| Case | Response |
|---|---|
| dataset not in the user's catalog | 403 errors.nl_query.dataset_forbidden, args.dataset |
missing or not exposed field (in select, filter, grouping, measure or sort) | 403 errors.nl_query.columns_forbidden, args.dataset and args.columns |
| invalid plan (operator, value type, depth, limits) | 400 errors.nl_query.invalid_plan, args.errors = [{ path, code, message }] |
| aggregate over too many rows | 400 errors.nl_query.too_many_rows (narrow the filter) |
feature disabled (NlQuery:Enabled=false) | 403 errors.nl_query.disabled |
The /nl-query page and the grid button
- "Ask your data" menu item at the root of the menu (route
nl-query): the chat in its data-questions variant; it resumes the user's last session (sessions are separate from the developer chat). - "Ask your data" button in the list-grid toolbar: opens
/nl-query?dataset=<route>&filterInfo=<active filter>. The grid becomes the context of the question. The server validates it: the dataset must be in the user's catalog (otherwise 403) and the filter is rewritten into the QueryPlan and validated; an invalid filter is dropped and the dataset is kept. The button does not appear on system routes and is hidden withextraProps.toolbar.hideAskData.
Answers, sources and "Open in grid"
- The answer cites numbers with
[n]: each[n]is the result of a tool (rows, aggregate or record). A deterministic check verifies that every cited number appears in its source; if it does not, the model corrects once, then the answer comes out with the "numbers not verified" warning (NlQuery:UnverifiedMode=flag) or with the sources only (table). - Sources panel: readable description of the plan, rows involved, "Show data" (reruns the plan with the viewer's permissions: table, and a chart for aggregates; rows are not stored), "Open in grid":
/<route>/list?filterInfo=<filter>, the route's grid with the same filter (for an aggregate: the rows before grouping, hence the same total). - Chart of an aggregate: a line chart, sorted by date, when the only grouping is a period (day, month, quarter, year); a bar chart otherwise, including a ranking of periods ("the 5 best months"), where a line with gaps would mislead. With several groupings the label is composite ("Rossi Srl · 2026-01"). There are at most 20 bars: beyond that the chart shows the top 20 by the value of the first measure and says so ("top 20 of 57"), while the table has all of them. A line is never cut (a stretch of time would be missing); with more than 100 periods the chart is not drawn and a note suggests a wider grouping. At most 3 series, one per measure. "Hide chart" removes only the chart and keeps the table; "Hide data" closes both.
Clarifying questions (ask_user)
When the question is ambiguous (which customer, which period, which dataset) the model does not guess: it ends the turn with a question and 2 to 6 options built from the real candidates. The user picks a button (or types a free answer, if allowed) and the choice arrives as the next question.
Asynchronous turn and notification
POST api/nl-query/sessions/{id}/askanswers immediately (assistant messagepending); the turn runs in the background with the identity and permissions of the user who asked.- During the turn the page shows the current step ("running the query on ..."); the outcome (answer with sources, clarifying question or typed error) arrives on the message and in the bell, with the link to the session (
/nl-query?sessionId=...&messageId=...): the user can leave the page. - Turn limits:
QuestionTimeoutSeconds,MaxToolRounds,QuestionTokenBudget,DailyTokenBudgetPerUser(errorserrors.nl_query.timeout,round_limit,token_budget,daily_budget). - Per-user limits, checked when the question arrives:
MaxPendingQuestionsPerUserquestions in progress andMaxQuestionsPerMinutePerUserquestions per minute (429errors.nl_query.too_many_pendinganderrors.nl_query.rate_limited,args.max). They apply per backend instance.
Views generated from questions
When explicitly asked to save the data as a view ("create a menu view with ...") the model proposes a view instead of answering:
- kind `view` (view builder): list of rows or details, also with the text of linked fields (lookups);
- kind `pivot` (pivot builder): totals, counts, groupings, series by day/month/year;
- materialized (
materialized: true,refresh=hourly|daily|weekly|monthly): table refreshed by a scheduler job, for large or slow data.
The presentation is declared in the proposal and validated by the server (columns[] with label and, for lookups, display = text | id | both; measures[] with the label of each pivot measure; all labels different): an inconsistent proposal goes back to the model with the reason.
Anyone sees the proposal; "Apply" belongs only to the superadmin verified on the DB (POST api/nl-query/sessions/{id}/messages/{messageId}/apply-view). The server revalidates the plan with the permissions of whoever applies it, creates the view or pivot, the read-only route (with the plan filter as default filter) and the menu item. Object name: NlQuery:ViewPrefix + proposed name (only [a-z0-9_], max 60), never overwritten (409 errors.nl_query.view_exists). Other errors: views_disabled, view_forbidden, view_not_proposed, view_failed.
Request to the administrator. When the proposal goes to a user who is not a superadmin, at the end of the turn every superadmin (superadmin role verified on the DB, users not deleted) gets the bell notification "user is asking for the view name" (type nlq.view.review, text in the reader's language). Clicking it opens /nl-query?kind=view-review&sessionId=..&messageId=..: instead of the chat the page shows who asked, the question, the answer and the proposal read-only, with the preview (run again with the superadmin's permissions) and "Create". If a superadmin asks, nobody is notified: they create the view themselves. There is no notification back to the author: the proposal on their message shows the outcome (view created and link to the menu entry) when they reopen the session. APIs reserved to the superadmin verified on the DB (403 view_forbidden for everyone else, 404 session_not_found if the message is not in that session, 409 view_not_proposed without a proposal or if it was already applied): GET api/nl-query/review/sessions/{id}/messages/{messageId} (read) and POST api/nl-query/review/sessions/{id}/messages/{messageId}/apply-view (same creation as "Apply", with appliedBy = the superadmin; the outcome is saved on the author's message and the proposal is applied only once).
Administrator configuration (curated datasets, descriptions, sensitive columns)
The superadmin configures "Ask your data" from the /nl-query page with the "Configure" button (dialog "Ask your data settings", visible only to the superadmin verified on the DB). The configuration lives in the nlQuery section of the metadata props bags, so it follows history, comparison, packages and promotions of the app lifecycle; the other keys of the props bag stay untouched.
| Where | Key | Effect |
|---|---|---|
route (md_props_bag.nlQuery) | exclude | dataset excluded from questions (even if it is in the menu) |
| route | include | curated dataset: non-system route outside the menu made queryable; permissions stay those of the engine (a denied table grant still removes it) |
| route | description, synonyms | description (max 500 characters) and synonyms (max 10 of 60) shown to the model and used in the dataset search |
| route | rowValues | false = aggregates only: counts and aggregates go to the model, rows only to the table below the answer (the most restrictive between this and NlQuery:SendRowValues wins) |
column (mc_props_bag.nlQuery) | exclude | sensitive column: never selectable, filterable or groupable |
| column | description, synonyms | description and synonyms of the field for the model |
{ "nlQuery": { "include": true, "description": "Giacenze di magazzino per articolo", "synonyms": ["giacenze", "scorte"], "rowValues": false } }API (verified superadmin only, otherwise 403 errors.nl_query.config_forbidden):
GET api/nl-query/admin/datasets: configurable routes (in the menu or not) with their configuration and the global appsettings values, read-only;GET api/nl-query/admin/datasets/{route}andPUT api/nl-query/admin/datasets/{route}with{ "dataset": { ... }, "columns": [{ "name": "...", "exclude": true, ... }] }: writes only what changes, in a transaction, then invalidates the metadata. Invalid configuration (excluded and curated together, texts too long) -> 400errors.nl_query.config_invalidwithargs.reason; unreadable props bag -> 409, never overwritten.
Configuration (NlQuery section of appsettings)
All keys are optional: the defaults are in the code (Services/NlQuery/NlQueryOptions.cs). Provider, key and engine of the model are not here: they are those of the RAG chat (rag-llm-provider, rag-llm-api-key). With rag-llm-api-key = agent-sdk the questions go through the claude CLI (subscription credit): the CLI runs without its own tools (no shell, files or web), only with the MCP server of the read-only tools and without the MCP servers configured for the user of the process; Model and Effort are passed to it.
| Key | Default | Meaning |
|---|---|---|
Enabled | true | feature enabled |
SendRowValues | true | row values sent to the model (false = counts and aggregates only) |
MaxRows | 50 | maximum rows of a rows query |
MaxGroups | 100 | maximum groups of an aggregate |
MaxInValues | 50 | maximum values in an in filter |
MaxFilterConditions | 20 | maximum conditions in a filter |
MaxAggregateSourceRows | 50000 | maximum source rows read for an aggregate |
MaxTextLength | 500 | maximum length of returned texts |
SensitiveColumns | [] | columns never exposed, route.column |
TimeZone | "" (server time zone) | time zone for relative periods (system id) |
Model / Effort | claude-opus-5-5 / low | model and effort of the questions |
LogRetentionDays | 90 | retention days of sessions and logs |
MaxToolRounds | 8 | tool rounds per question |
MaxTokensPerCall | 16000 | max_tokens of each call |
QuestionTokenBudget | 400000 | tokens per question |
DailyTokenBudgetPerUser | 3000000 | tokens per user per day (cache reads included) |
MaxPendingQuestionsPerUser | 2 | questions in progress per user (0 = no limit) |
MaxQuestionsPerMinutePerUser | 10 | questions per minute per user (0 = no limit) |
QuestionTimeoutSeconds | 120 | maximum time of a question |
MaxDistinctValues | 50 | values returned by distinct_values |
HistoryTurns | 5 | previous questions given as context |
UnverifiedMode | flag | unverified citations: flag (warning) or table (sources only) |
RefusalFallback | default | server-side fallback on model refusals: default or none |
ViewsEnabled | true | views generated from questions |
ViewPrefix | nlv_ | prefix of the generated views' objects ([a-z][a-z0-9_]{0,9}) |
{
"NlQuery": {
"SendRowValues": false,
"SensitiveColumns": ["customers.CreditLimit"],
"TimeZone": "Europe/Rome"
}
}Deterministic API (no model)
With the user's session (cookie k-user), for integrations and tests: no model call.
GET api/nl-query/datasets?q=<text>: the user's catalog (key,label,description,menuPath).GET api/nl-query/datasets/{dataset}: exposed fields (name,label,kind=Text|Number|Date|DateTime|Bool|Lookup|Dictionary,isKey,lookupRoute, dictionary entries).POST api/nl-query/plan/execute: runs a QueryPlan (JSON body).
QueryPlan: dataset, select (rows only), filter ({field, op, value} or groups {all:[...]} / {any:[...]}, at most two levels), groupBy (at most 3, {field, bucket: day|month|quarter|year} on dates), measures (count|sum|avg|min|max, count also without a field), sort (by = field, grouping or measure name), limit. Operators: eq, neq, gt, gte, lt, lte, contains, startswith, endswith, in, between, period (today, this_month, last_30_days, this_year, ...), isnull, notnull, allowed according to the field kind. Unknown properties = error with their 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": 10Response (excerpt): kind (rows | aggregate), columns, rows (for lookups also <field>__text), matchedRows, totalGroups, truncated, measureColumns and the citation source with gridUrl:
{
"ok": true,
"result": {
"kind": "aggregate",
"dataset": "orders",
"rows": [{ "SalespersonPersonID": 8, "SalespersonPersonID__text": "...", "ordini": 213 }],
"matchedRows": 1830,From WUIC Assistant and Claude Code (personal token)
The same tools, the same instructions and the same checks as the app chat, read from the backend: no client keeps a copy.
1. apiTokensEnabled=true (see AppSettings).
2. User menu, "API tokens" item: new token with the "Data questions (WUIC Assistant)" checkbox (scope nl-query). The token (wuic_pat_...) is shown only once.
3. In WUIC Assistant: command "WUIC Assistant: Imposta token API WUIC". In Claude Code (or another MCP client): WUIC_API_TOKEN variable in the env of the wuic-rag server in .mcp.json:
{
"mcpServers": {
"wuic-rag": {
"command": "node",
"args": ["scripts/mcp/wuic-rag-mcp.mjs"],
"env": {
"WUIC_BACKEND": "http://localhost:5000",The MCP server opens a conversation (POST api/nl-query/tools/session, only with Authorization: Bearer; the cookie does not count here) and adds the nlq_* tools:
nlq_instructions: rules and workflow from the backend, to be read first;nlq_list_datasets,nlq_describe_dataset,nlq_distinct_values,nlq_query_rows,nlq_aggregate,nlq_get_record: reads with the token owner's permissions, each with itscite_id;nlq_nl_verify_answer: check of the answer's citations before giving it to the user;nlq_ask_user: validates the clarifying question, which the client asks with its own mechanism;nlq_propose_view: view proposal (no writes);- action `nlq_apply_view` (
annotations.destructiveHint, description "[Requires explicit user approval]"): creates the proposed view with the same input, only after the user's explicit approval and only if the token owner is a superadmin.
Errors: token without the nl-query scope -> 403 errors.auth.api_token_scope; revoked or expired token, or feature disabled -> 401 immediately, even with an open conversation. A conversation lasts 60 minutes and the MCP server opens a new one on its own.
Measured accuracy (eval)
Eval with the model of the plan (Claude Opus 5.5, claude-opus-5-5, effort low, agent-sdk engine) on 108 questions about the WideWorldImporters data (23/10/2026). The expected answers are computed with hand-written SQL, with the user's restrictions written explicitly; the questions are asked by three users with different permissions.
| Metric | Threshold | First run | After the fixes |
|---|---|---|---|
| correct numeric answers (90 questions with an answer) | >= 90% | 88/90 | 90/90 |
| verified citation and "Open in grid" link with the same rows | >= 95% | 76/82 | 84/84 |
| correct refusals, "I don't know" and clarifying questions (18) | >= 90% | 18/18 | 18/18 |
| out-of-scope data or instructions in the data executed | 0 | 0 | 0 |
- Categories: counts and sums, filters and periods, groupings, top-N, period comparisons, record lookups, permissions (rows, denied routes and columns, system tables, passwords), administrator configuration (curated dataset, aggregates only, sensitive columns, excluded dataset), malicious instructions in the data, unanswerable or ambiguous questions, questions in English, French, German and Spanish.
- "After the fixes" = re-run of the failed cases only, after fixing the citation check and the prompt.
- Latency: median 16 s, 95th percentile 37 s. Cost: about USD 0.08 per question at list prices.
Limits
- Verified with database tests on SQL Server, MySQL, PostgreSQL and Oracle (catalog, operators, relative periods, aggregates, generated views).
- Aggregates over
MaxAggregateSourceRowsrefused;innot allowed inside a nestedallgroup. - Without a license (Trial) the engine reads at most 20 rows: questions over at most 20 rows are answered normally, beyond that the answer is refused (
errors.nl_query.license_limited) because it would not be complete. - Generated views (rows, materialized, pivot) on all four DBMS; view filter in AND only.
- Relative periods computed in the
TimeZone(or the server's) and fixed when a view is applied.
Screenshot

![Answer to "How many orders did each salesperson handle in January 2015?": table by salesperson, citation [1] and "Verified numbers"](https://wuic-framework.com/assets/wuic-framework-docs/screenshots/manual__nl-query__02.png)

