Ask and trace
How to ask good questions, how the analyst chooses its path, and how to read an answer, its labels, its sources and its full trace.
Ask
Open Ask, or press N from anywhere. Ask the way you'd ask a colleague: "What was MRR last month, by plan?"
- Enter sends, Shift+Enter adds a line, Esc stops a run.
- While a run is working, anything you type is added to your question, and the analyst reads it before its next step.
- The @ button points the analyst at something specific: a metric, dataset, guide, verified query, skill or dashboard. The paperclip, paste or drop adds a file or an image (text, CSV, HTML, PDF, PNG, JPEG). Up to five attachments, at most two of them images.
- The analyst reads every source you can read. Sample data is marked as such and never mixed with your own.
- Choose the model, provider and thinking level in the composer: Low, Medium, High, Extra or Max, as the model allows. Your choice is remembered in your browser.
- Ask a follow-up in the same conversation; the analyst keeps the context.
- ⌘J (Ctrl+J) opens the analyst beside any other page, such as a dashboard you're looking at.
- Ask for a dashboard and the analyst plans and builds one.
Viewers can read what's shared with them but can't ask. See Workspaces and roles.
How the analyst answers
The analyst searches your knowledge, then takes the most governed path that can answer:
- A verified query that matches the question, used as a template (adapting the period, never replayed blindly).
- A metric query over approved definitions.
- SQL over datasets.
- Raw SQL over the tables, as a last resort. It is labelled, and always cross-checked.
Every query goes through the query gateway: read-only, time-limited, and checked for the traps of each SQL dialect.
It can also read connected services such as Jira. A call that would change something there shows exactly what it would send, and runs only when you press Allow once.
A run that reaches the workspace's limit for one run pauses and asks before it continues.
Read the answer
Under each answer: Copy, Sources, Trace, Remember, PDF (the answer as a PDF to send on), Repeat… (a routine from it) and, on a metric answer, Watch. Every query the analyst ran in the conversation opens to its SQL and rows.
Labels
| Label | Meaning |
|---|---|
| Metric | Built from definitions an admin approved. |
| Unmodelled | SQL written over the tables. Cross-checked, but not from a governed definition. |
| Unverified | The answer gate couldn't check every number. The answer is still shown, so you can see why. |
| Not answered from your data | The analyst couldn't answer from the data, and says so instead of guessing. |
Numbers
Every number is a link. Open it to see the query cell it references and the records behind it, the rows that make up the figure. Download this page saves them as CSV. Personal-data columns are hidden, and the panel says so.
If a number is wrong, use This number is wrong on it. See Learning loop.
Sources panel
| Tab | What it shows |
|---|---|
| Interpretation | How the analyst read your question, including any reading it had to choose. |
| Context | The glossary terms, guides, definitions and skills it used. |
| Queries | Every query it ran, with the SQL. |
| Checks | What the answer gate checked, and the cross-check of the headline number. |
| Couldn't verify | Only when something failed: what the gate couldn't check. |
Trace
The trace shows the whole run: status, time, model calls, tokens (and how much was cached), cost, and a timeline of every model call and tool call. It is how you find out why an answer came out the way it did.
When an answer used the asker's personal memory, other readers see only the structure of the run.
The answer gate
The model never types a number. It cites cells of recorded query results, and the gate:
- resolves each reference to its cell;
- recomputes derived values (differences, ratios, shares);
- checks the claims around the numbers;
- requires a cross-check for the headline number.
An answer that fails goes back to the analyst. If it still fails, it ships marked Unverified, never hidden and never silently "fixed".
From the terminal
Developers can ask from the command line and watch the run as it happens:
pnpm ask "What was MRR last month, by plan?"It prints the thinking, SQL, results, the gate's problems and the answer.
Connect a source
Connect PostgreSQL, MySQL or ClickHouse through a read-only user, choose what OpenDash learns, and keep the connection safe.
Datasets and metrics
OpenDash's semantic layer. Datasets describe your tables in small YAML files, metrics name the numbers that matter, and both compile to safe SQL.