Ask Your Data (natural-language query)

On the SQL Editor page, an Ask your data box turns a plain-English question into a read-only SELECT, runs it, and shows both the answer grid (first 200 rows; the query itself capped at 10,000) and the generated SQL with a short explanation. “Open in editor” drops the SQL into the SQL Editor for tweaking/export; it never auto-runs.

Same guardrails as everything else — read-only validation (a single SELECT/WITH … SELECT; anything that writes/EXECs is blocked before running), RLS under your identity, and scope-restricted keys only ever told about their own tables (and, like the raw SQL editor, refused unless the key carries the AllowRawSql opt-in — then its generated SQL is database-enforced against the key’s scope grid, fail-closed). Requires sql.execute (Admin/Owner by default); each question is audited as SQL_NL_QUERY, and it does not trigger the SQL Editor’s per-run TOTP prompt (you never hand-write the SQL).

It uses your organization’s own Anthropic API key, set (encrypted, never shown back) under Settings → AI / Natural-language query; until a key is set the box shows a “not set up yet” panel.

Definitions (business meanings). Two optional layers teach the model — and MCP agents — what your data means; both are edited by admins with dab.manage:

• Column meanings — per-column business descriptions, set on an entity’s gear under DAB Config → Global Scope → Column Meanings (e.g. cust_stat → “Churn status: A=active, C=churned”). Up to 400 chars each.
• Business definitions — cross-table terms/metrics (e.g. revenue = paid invoice total) with an optional advisory SQL hint, edited in the AI / Natural-language query card under Settings. Capped at 100 terms / 8 KB.

Definitions feed both the Ask box and MCP describe_entities: column meanings and entity descriptions become the field descriptions returned to AI agents (e.g. "description": "Churn status: A=active, C=churned. NVARCHAR(1), NOT NULL"). The Ask box picks them up immediately; the MCP side updates on the next Restart DAB.

Export downloads nl-definitions.json — a schema skeleton with your current definitions plus blank slots for every exposed entity/column — that an external AI can fill in; Import merges it back, validated: it reports how many terms/meanings/descriptions applied and skips anything hallucinated (an entity/column that doesn’t exist) or over the length/count cap. A blank meaning never erases an existing one unless you explicitly replace.