Analytics / Query Agent

The backend agent that turns a plain-language question into a safe, constrained query, runs it against your real data, and returns the answer — without ever exposing raw database access.

What Is the Analytics / Query Agent?

The Analytics / Query Agent is one of TotalApp's Core Agents. It turns a plain-language question — "Who were our riskiest suppliers last month?" — into a safe, constrained SQL or GraphQL query, runs it against your real data, and returns the answer in plain language, without ever exposing raw, unconstrained database access.

Getting an answer from company data usually means either knowing SQL or waiting on a data team. The Analytics / Query Agent removes that bottleneck by translating a natural-language question directly into a query, but only within a defined, policy-constrained query surface — it never runs arbitrary queries the requester's schema and permissions wouldn't otherwise allow.

In one sentence

Ask a question in plain language — the agent translates it into a constrained query, runs it, and returns a plain-language answer alongside the exact query and raw result so it can be verified.

How It Works — Translate, Constrain, Explain

1. Query Translation → 2. Constrained Execution → 3. Plain-Language Insight

Phase	What happens
1. Query Translation	The natural-language question is translated into SQL or GraphQL against a defined safe query surface. Ambiguous questions are clarified with a follow-up rather than answered with a guess.
2. Constrained Execution	The agent never generates arbitrary queries outside what your schema and policies permit — RBAC and tenant scoping apply exactly as they would to any other data access in TotalApp.
3. Plain-Language Insight	Query results are summarized in plain language, not just returned as raw rows. Both the underlying query and the raw result are shown alongside the summary, so the answer is verifiable, not just trusted.

Verifiable by design

The generated query and its raw result are never hidden behind the summary — showing both is a deliberate choice so anyone can check exactly what was asked of the database and what came back, rather than trusting a paraphrase.

Key Capabilities

Natural Language In

Ask a question the way you'd ask a colleague — no SQL knowledge required to get a real answer from your data.

Constrained Query Surface

Never arbitrary database access — only what your schema and policies explicitly allow, applied the same way every time.

Plain-Language Answers

Results summarized in words, not just returned as a raw table dump — closing the gap between "I have data" and "I have an answer".

Verifiable Every Time

The underlying query and raw result are always shown alongside the summary — nothing is a black box.

Relationship to the 2-Tier Architecture

The Analytics / Query Agent is the exact-match retrieval half of TotalApp's 2-Tier Architecture — deterministic, structured queries against known schemas — complementing the RAG / Knowledge Agent's fuzzy, meaning-based retrieval over unstructured documents. Together they cover both "what does the data say exactly" and "what do our documents say about this".

Frequently Asked Questions

Can this agent run any query I ask it, in theory?

No — it only ever generates queries within a defined, policy-constrained query surface. It is explicitly built to never expose raw, unconstrained database access, regardless of how the question is phrased.

What happens if my question is ambiguous?

The agent asks a clarifying follow-up rather than guessing at intent and returning a potentially wrong answer confidently phrased as correct.

Does RBAC still apply when I ask a question in plain language?

Yes — RBAC and tenant scoping apply exactly as they would to any other data access route in TotalApp. Asking in natural language doesn't bypass any entitlement check.

Are my questions and their results logged?

Yes — every query is logged for review of what was asked and what was returned, supporting later audit of how the agent has been used.