How answers are built¶
Every answer from an AI Analyst is the result of a series of steps: looking up what's in your semantic layer, running one or more queries, building charts or a report, and then writing the reply. Actian AI Analyst shows those steps in the conversation, so you can see how an answer was reached and check the queries behind it.
Where you see the steps¶
The steps appear in the same way in three places:
- Explorer conversations, including conversations shared with you in read-only mode.
- The Test panel in Studio, where your data team tries out an analyst before deploying it.
- The conversation replay under Monitoring in Studio (AI Analysts → your analyst → Monitoring).
Tip
Anyone who can open a conversation can expand its steps and see the inputs and outputs, including people you share the conversation with.
Following an answer while it runs¶
When you send a question, a short status line such as Starting… or Thinking… appears until the first step shows up.
As soon as the Analyst starts working, the steps appear as a one-line, collapsible summary:
- While any step is still running, the summary reads Working… · N steps, and the list stays open so you can watch the progress.
- When every step has finished, it reads Worked for N seconds · N steps, and the list collapses once the answer arrives.
Click the summary to open or close it. Your choice stays in place, even after the answer finishes.
A long answer can have more than one summary. Steps are grouped in the order they happened, between the parts of the written answer they led to.
Charts and tables appear when the answer finishes. A report can build in its panel while the Analyst is still working. See Reports.
Reading a step¶
Each row in the list shows:
-
A status dot:
Dot Meaning Pulsing blue The step is still running (the row also shows Running…). Green The step finished. Amber The step finished but returned an error. The error message appears under the row. Red The step was rejected and did not run. Grey The step was still unfinished when the answer ended. -
The step's name, for example Run metric or List models.
- How long the step took, in milliseconds (
ms) under one second and in seconds (s) otherwise.
Rows labelled Thinking show the model's own reasoning between steps.
Click a row to expand it. Most steps show:
- Input: what the Analyst passed to the step, as a list of values (or as JSON when the values are nested). No arguments means the step took no input.
- Output: what the step returned.
The lookup steps (List models, List metrics, List glossary terms and Search semantic layer) show Output · N results as a list of the models, metrics or Glossary terms found. Where a name can be matched, it links to that item's page in Studio.
Query steps show the calculation behind the result: the metric or model query, the SemQL and the SQL it compiled to, and the number of rows returned.
What each step does¶
The step names below are the names you see in the conversation. Not every answer uses every step.
Looking things up¶
| Step | What it does |
|---|---|
| List models | Lists the Models this analyst can query, with their dimensions, measures, filters and relationships. |
| List metrics | Lists the Metrics this analyst can run, with their definitions and the ways they can be sliced. |
| List glossary terms | Looks up Glossary terms: their definitions, synonyms and the data they map to. |
| Search semantic layer | Searches the semantic layer by meaning or by name for relevant Models, fields, Metrics and Glossary terms. |
These steps only read the semantic layer. They don't query your warehouse, and they return only what this AI Analyst has been given access to. To change what an analyst can use, see Models.
Running queries¶
| Step | What it does |
|---|---|
| Run metric | Queries one curated Metric. |
| Query a model | Runs a structured query on one Model, without joins. |
| Run SemQL query | Runs a free-form SemQL query, used when neither of the other two fits (for example joins, window functions or combining several results). |
About query steps:
- Each query returns up to 100 rows by default and never more than 1,000.
- Every successful query saves its result as a named table. The table only appears in the conversation when a Present step shows it, or when it is part of a report that is presented.
- The step log keeps the compiled SQL, the row count, whether the result was cut off at the row limit, the duration and the lineage. It doesn't keep the rows themselves. You see the data through the table, chart or report that the Analyst presents.
- If a query fails, the row turns amber and shows the error. The Analyst can then rewrite the query and try again.
Showing results¶
| Step | What it does |
|---|---|
| Create chart | Makes a chart from a table that a query already produced. |
| Present | Shows a chart, table or report in the conversation. Each item is shown at most once per answer. A chart or table that is part of a presented report isn't shown again on its own. |
| Create report | Starts a report. |
| Update report | Adds to or changes the report. |
| Read report | Reloads the report's current content, for example after a conflicting edit. |
See Reports and Artifacts for what you can do with the results.
Consulting guides¶
| Step | What it does |
|---|---|
| Consult a guide | Opens one of the built-in guides. |
| Search guides | Searches the built-in guides. |
| Read a guide | Reads part of a built-in guide. |
The guides are working instructions that ship with AI Analyst. They cover querying (including a SemQL reference), chart creation, report writing, schedule management and scheduled runs. The Analyst normally consults the querying guide before its first query in an answer.
The row names the guide or the search, for example Consult a guide · Querying. These rows don't expand, and the guide text is never shown. You can't edit the built-in guides. To shape how an analyst behaves, your data team edits its Instructions in Studio.
Scheduling from a conversation¶
You can ask the Analyst to set up, list or remove Scheduled Insights for you.
Availability
- Plan: Scheduled Insights must be included in your plan. See Scheduled Insights for the limits that apply.
| Step | What it does |
|---|---|
| Create schedule | Creates a Scheduled Insight that you own, using the analyst you are talking to. It is live as soon as it is created; there is no draft. |
| List schedules | Lists your own schedules. |
| Delete schedule | Permanently deletes one of your own schedules. The Analyst normally confirms with you first. |
Create schedule applies the same checks as creating a schedule in Explorer: your plan must include Scheduled Insights, and the schedule must respect your plan's minimum interval and limit on active schedules. Create schedule and Delete schedule can't be used during a scheduled run.
Steps used in scheduled runs¶
| Step | What it does |
|---|---|
| Create inbox item | Saves a finding to the schedule owner's Inbox. It only works during a scheduled run. |
| List task artifacts | Lists the names, titles and types of the charts, tables and reports from one of your own conversations, without their contents. A scheduled run uses it to find the previous run's results when its instructions ask for a comparison. |
A scheduled run that finds nothing worth reporting creates no Inbox item. An email copy of the finding, including the run's charts, is sent to the schedule owner only when the schedule's instructions ask for email. Your plan sets a limit on Inbox items per scheduled run.
Steps that don't appear as rows¶
Two steps never show up in the list, because they have their own place in the conversation:
- Note assumptions: judgment calls the Analyst made on your behalf that changed the numbers, such as a time window it chose or a definition it supplied, appear in an Assumptions block under the answer.
- Present plan: in Plan Mode, the plan appears in a Suggested plan card. If you can reply to the conversation, the card takes the place of the message box and offers Approve, Edit, Keep planning and Cancel, with an Add a note (optional) field. People viewing the conversation in read-only mode see the plan without these buttons.
In a Plan Mode answer, the Analyst can't run queries, create charts, present results or build a report. It looks things up, consults the guides, and then presents its plan.
Steps that reach beyond the conversation¶
| Step | What it does |
|---|---|
| Send semantic-layer feedback | Reports a gap in the semantic layer to your data team. See When the Analyst flags something for your data team. |
| Note an issue | Records a diagnostic note for Actian about a problem in the product itself. See When the Analyst notes an issue for Actian. |
Steps from older conversations¶
If a conversation used a step that AI Analyst no longer has, the row shows a readable version of the step's internal name instead of one of the names above.
Limits on each answer¶
- An answer can run up to 40 queries. Failed attempts count toward this limit.
- After that, the Analyst must answer with what it has. It can no longer run queries, but it can still look things up, make charts, present results, work on the report and consult the guides.
If an answer stops short, ask a narrower follow-up question, or split the question into parts. See Tips for Asking Questions.
When the Analyst flags something for your data team¶
Sometimes the Analyst runs into a gap that your data team could fix in the semantic layer. For example:
- A Metric it needed is missing.
- A field, join or relationship it needed isn't modelled.
- A definition or description is misleading.
- A Model that is relevant to your question is one this analyst isn't allowed to use.
When that happens, it can add a Send semantic-layer feedback step. The step files a note for your data team. It never changes the semantic layer.
The Analyst normally files one note for each distinct issue it can't resolve, usually near the end of its answer, and tells you briefly that it flagged an improvement. It may still give you an answer that works around the gap. This behavior comes from the Analyst's instructions, so it won't flag every gap every time.
What is sent¶
Expand the Send semantic-layer feedback row to see exactly what was filed:
- A short feedback note, up to 500 characters.
- The context: what you asked or what the Analyst was trying to do, up to 1,000 characters.
The note is linked to this conversation and to the answer it came from.
Failed queries are reported automatically¶
When a Run metric, Query a model or Run SemQL query step fails because of a semantic-layer or execution problem, AI Analyst also reports it to your data team automatically. No extra step appears in the conversation. Execution problems include a column or table that no longer exists in the warehouse, and a warehouse permission error.
Each report holds the start of the error message and a link to the conversation and answer. Up to about three failures are reported per answer. Queries that fail to parse, or that are rejected as unsupported or unsafe, aren't reported. Failures where the query refers to something the semantic layer doesn't have are reported, because they can point to a gap in it.
What isn't reported¶
Questions asked in the Studio Test panel are never reported. Testing an analyst doesn't send anything to the data team.
The Analyst is also told not to flag the following. This comes from its instructions, so it doesn't always hold:
- Problems with the data in your warehouse, such as missing or incorrect values.
- Differences between SQL dialects, and limitations of the product itself. The Analyst reports product problems to Actian instead, with Note an issue.
- Normal query work, and questions your warehouse doesn't hold data for.
What happens next¶
Reports don't reach your data team one at a time. They are collected and reviewed in batches by the Steward. A review starts when several reports have built up, when the oldest report is about a day old, or straight away for urgent problems such as a failed warehouse connection test.
The Steward checks the reports against the semantic layer, the warehouse and the conversation they came from. Reports with the same cause are grouped into one item in the Steward's Inbox in Studio: an alert, a suggestion with a proposed plan, or an insight. The Steward may add reports to an existing item, or skip reports it judges to be noise, so not every report becomes an item. Nothing in the semantic layer changes until a member of your data team approves a plan. See Steward Inbox.
Your data team can see the conversation
Each Inbox item lists the conversations it was based on under Analyzed conversations. Each one shows the conversation's first question and the name of the person who asked it, and opens the conversation in Studio. The item's message may also quote example questions.
When the Analyst notes an issue for Actian¶
If the Analyst runs into a problem with AI Analyst itself rather than with your semantic layer, it can add a Note an issue step. The step records a short diagnostic note for Actian engineering.
The row doesn't expand, so its content isn't shown in the conversation. Depending on how your deployment is set up, the note is sent to Actian or kept on your installation. On air-gapped self-managed deployments, notes stay on the installation, and an administrator can include them in the diagnostic export for Actian.
To report a problem yourself, see Rating answers and reporting problems.