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 schema wuic) and routes with md_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 in NlQuery:SensitiveColumns (form route.column).
  • Blocked with a reason: a request on data that is not exposed returns nothing and says why.
CaseResponse
dataset not in the user's catalog403 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 rows400 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 with extraProps.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}/ask answers immediately (assistant message pending); 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 (errors errors.nl_query.timeout, round_limit, token_budget, daily_budget).
  • Per-user limits, checked when the question arrives: MaxPendingQuestionsPerUser questions in progress and MaxQuestionsPerMinutePerUser questions per minute (429 errors.nl_query.too_many_pending and errors.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.

WhereKeyEffect
route (md_props_bag.nlQuery)excludedataset excluded from questions (even if it is in the menu)
routeincludecurated dataset: non-system route outside the menu made queryable; permissions stay those of the engine (a denied table grant still removes it)
routedescription, synonymsdescription (max 500 characters) and synonyms (max 10 of 60) shown to the model and used in the dataset search
routerowValuesfalse = 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)excludesensitive column: never selectable, filterable or groupable
columndescription, synonymsdescription and synonyms of the field for the model
Snippet 1JSON
{ "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} and PUT 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) -> 400 errors.nl_query.config_invalid with args.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.

KeyDefaultMeaning
Enabledtruefeature enabled
SendRowValuestruerow values sent to the model (false = counts and aggregates only)
MaxRows50maximum rows of a rows query
MaxGroups100maximum groups of an aggregate
MaxInValues50maximum values in an in filter
MaxFilterConditions20maximum conditions in a filter
MaxAggregateSourceRows50000maximum source rows read for an aggregate
MaxTextLength500maximum length of returned texts
SensitiveColumns[]columns never exposed, route.column
TimeZone"" (server time zone)time zone for relative periods (system id)
Model / Effortclaude-opus-5-5 / lowmodel and effort of the questions
LogRetentionDays90retention days of sessions and logs
MaxToolRounds8tool rounds per question
MaxTokensPerCall16000max_tokens of each call
QuestionTokenBudget400000tokens per question
DailyTokenBudgetPerUser3000000tokens per user per day (cache reads included)
MaxPendingQuestionsPerUser2questions in progress per user (0 = no limit)
MaxQuestionsPerMinutePerUser10questions per minute per user (0 = no limit)
QuestionTimeoutSeconds120maximum time of a question
MaxDistinctValues50values returned by distinct_values
HistoryTurns5previous questions given as context
UnverifiedModeflagunverified citations: flag (warning) or table (sources only)
RefusalFallbackdefaultserver-side fallback on model refusals: default or none
ViewsEnabledtrueviews generated from questions
ViewPrefixnlv_prefix of the generated views' objects ([a-z][a-z0-9_]{0,9})
Snippet 2JSON
{
  "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.

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

Response (excerpt): kind (rows | aggregate), columns, rows (for lookups also <field>__text), matchedRows, totalGroups, truncated, measureColumns and the citation source with gridUrl:

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

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

MetricThresholdFirst runAfter the fixes
correct numeric answers (90 questions with an answer)>= 90%88/9090/90
verified citation and "Open in grid" link with the same rows>= 95%76/8284/84
correct refusals, "I don't know" and clarifying questions (18)>= 90%18/1818/18
out-of-scope data or instructions in the data executed000
  • 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 MaxAggregateSourceRows refused; in not allowed inside a nested all group.
  • 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

/nl-query page with the initial message, the suggestions and the question box
/nl-query page with the initial message, the suggestions and the question box
Answer to "How many orders did each salesperson handle in January 2015?": table by salesperson, citation [1] and "Verified numbers"
Answer to "How many orders did each salesperson handle in January 2015?": table by salesperson, citation [1] and "Verified numbers"
Source opened with "Show data": chart of orders by salesperson and "Open in grid" link
Source opened with "Show data": chart of orders by salesperson and "Open in grid" link
Administrator configuration: curated or excluded datasets, description for the model, synonyms and sensitive columns
Administrator configuration: curated or excluded datasets, description for the model, synonyms and sensitive columns