Skip to content
M↓ View as Markdown ↗

Instructions

Instructions tell your AI Analyst how to think, act and answer in your business context. In Studio the tab describes them as "Guidance this analyst follows on every question — its persona, priorities, and how to answer."

Think of instructions as onboarding a new analyst: what context would you give them so they avoid mistakes?

Availability

  • Who can do this: members with the Edit capability in the active Workspace. Other members who can open Studio see the instructions read-only.
  • Deployment: Actian SaaS and self-managed deployments.

How instructions are used

Actian AI Analyst adds your instructions to every question the AI Analyst answers, so it always sees them before it answers. Use them for business context, preferred ways of working and cautions. An AI Analyst with no instructions gets no extra guidance.

Saved instructions take effect from the next question, including for an AI Analyst that is already deployed in Explorer, Slack or Teams. To go back to an earlier wording, use Version history in the AI Analyst's header.

Edit instructions

  1. In Studio, click AI Analysts and select the AI Analyst.
  2. Open the Instructions tab.
  3. Write or change your guidance in the editor.
  4. Click Save changes.

Until you save, the bar at the bottom of the tab shows Unsaved changes. If you ask a question in the Test your analyst panel, your pending edits are saved first.

What to write

The What to write? list on the tab suggests five kinds of content:

Topic Example
Basic company info "This is a high-end furniture retailer. Products range from $200–$5000, so individual transactions are high-value."
Communication style "Answer in short paragraphs, lead with the number, and state the date range you used."
Brief data overview "You're working with logistics data across warehouses, shipments and inventory levels."
Analysis preferences "Segment performance by store type: Flagship, Outlet, Regular."
Data quirks "Treat 9999 in numeric fields as missing and exclude it from aggregations."

Also include common pitfalls to avoid, for example: "Promotions may be fixed or percentage-based. Always align promotion dates with order dates."

What not to write

The What not to write? list on the tab warns against:

  • Very specific query examples. Use the semantic layer instead: define metrics and add Guidance to models and metrics.
  • Generic instructions such as "you analyze data". The AI Analyst already knows its role.
  • Data access settings. Choose the models, metrics and glossary terms the AI Analyst can use on its Models and Glossary tabs, not in instructions.

Warning

Never put passwords, API keys, tokens or other secrets in instructions. Instructions are sent to the AI Analyst with every question.

Instructions or the semantic layer?

Some guidance works better somewhere other than in instructions:

Guidance Where to put it
Persona, business context, communication style, rules that apply across your data Instructions
A reusable calculation, such as inventory_value = retail_price × quantity_on_hand A metric
A note that applies to one model or one metric That model's or metric's Guidance field
The meaning of a business term A glossary term
Which data the AI Analyst can use The Models and Glossary tabs

Industry examples

Retail

  • Always analyze performance by store type (Flagship, Outlet, Regular).
  • For inventory analysis, join both the stores and products tables. Define inventory_value = retail_price × quantity_on_hand as a metric so every question uses the same calculation.
  • Be cautious with discount logic: some discounts are fixed amounts, others are percentage-based. Always check that promotion_date aligns with order_date.

Logistics

  • Use delivery_delay_days to measure shipping performance.
  • Exclude items with status = "discontinued" when calculating inventory metrics.
  • Segment warehouse data by region to identify bottlenecks.

Survey

  • Apply weighting using the weight_factor column when calculating averages or distributions.
  • Exclude responses where completion_time < 60 seconds. These are likely low quality.
  • Handle special codes: treat 9999 in numeric fields as missing data and exclude it from aggregations.

Iterate on your instructions

The AI Analyst follows your instructions in most cases, but not always perfectly. If it gives a wrong or incomplete answer:

  1. Reword or add to your instructions, then save.
  2. Ask the same question again in the Test your analyst panel.
  3. Repeat with a few different questions until the answers are consistent.

If a change makes things worse, restore an earlier version from Version history.

Tip

The Steward can also propose changes to an AI Analyst's instructions. It applies them only once the change is approved.