Using Steward¶
Steward is your AI assistant for building and maintaining your semantic layer: your data models, metrics, and business logic. You describe the change you want in plain language. Steward finds the right entities, drafts the edits, and, by default, shows them to you for review before it applies them.
Availability
- Who can do this: members with the Edit capability in the active Workspace.
- Deployment: Actian SaaS and self-managed deployments. Web search isn't available on air-gapped self-managed deployments.
Steward lives in Studio and needs the Edit capability in the active Workspace. Members who reach Studio only through another capability can't use Steward to make changes, and Steward reports that the Workspace is read-only. Edit also covers Steward's memory, saved prompts, tool permissions and file attachments.
Each Workspace has its own Steward memory, saved prompts and tool permissions. Steward works with the semantic layer and AI Analysts of the active Workspace only.
What Steward can do¶
Steward builds and changes your semantic layer, so you can start from scratch with a new data source or refine an existing setup.
- Explore your semantic layer and warehouse. Steward lists and searches models, metrics, glossary terms, data sources and AI Analysts, and inspects warehouse tables and their columns.
- Query data. Steward can run SemQL queries and metrics to check its work. It can also run SQL against a warehouse. SQL queries are read-only and can't change any data.
- Build and edit the semantic layer. Steward creates and updates models, dimensions, measures, filters, relationships, metrics and glossary terms. It identifies what a request depends on. For example, if a metric needs a measure or relationship that doesn't exist yet, Steward proposes that too.
- Create and configure AI Analysts. Steward can create an AI Analyst or change an existing one. It can rename the analyst or change its description, replace its instructions, connect or disconnect models (optionally limited to specific dimensions and measures), set its glossary access, and replace its Explorer suggestion cards. Steward can't deploy an analyst or change who can use it. Use Deploy on the analyst's page in Studio for that.
- Diagnose analyst answers. Steward can search and read recent AI Analyst conversations in the Workspace to work out why an analyst answered the way it did. It can filter them by status and by analyst name.
- Research your business. Steward can search the web for context about your company and industry, where web search is available on your deployment.
- Follow built-in guides. Steward uses built-in guides for common jobs: setting up AI Analysts, models, metrics and glossary terms, querying, importing definitions from files, first-time setup, deleting entities safely after checking dependencies, and analyzing analyst conversations.
Analyst conversations are visible to Steward
When Steward searches AI Analyst conversations, it searches the conversations of everyone in the Workspace, not only yours. It never returns Steward sessions. Secret-like values are redacted from the conversations it reads.
Open Steward¶
- In Studio, select Steward on the right edge of the window. The Steward panel opens.
- Type a request in the composer, or start from one of Steward's suggestions on the Inbox tab.
- Press Enter or select Send.
The Steward panel isn't shown on small screens or while your organization is locked.
You can also start Steward from other places in Studio:
- Models → New model → With Steward opens Steward with a starter prompt for you to complete. See Creating models with Steward.
- Fix with Steward appears next to a validation error on a metric's expression. It sends Steward a request with the failing expression and the error message.
Sessions and history¶
Each conversation with Steward is a session.
- To start a new session or return to the session list, select Back to sessions (the arrow at the left of the Steward header), then send a new request.
- To reopen an earlier session, select the History tab. It lists your own past Steward sessions in this Workspace.
Steward sessions don't appear in the Explorer conversation list.
The Inbox tab holds alerts, suggestions and insights that Steward finds on its own. See Steward Inbox.
Getting started¶
The best way to start is to give Steward context about your business. Run the /init saved prompt, or describe what you're working with:
"I just connected our sales database. We're a B2B SaaS company and we care most about MRR, churn, and customer acquisition cost."
Type / in an empty composer to pick a saved prompt. Choosing one replaces the composer text with the prompt. Any [bracketed] hint is selected so you can type over it, and Tab moves to the next one. /init asks Steward to research your company on the web, ask you a few questions, and save what it learns to its memory. If web search isn't available on your deployment (for example, on an air-gapped deployment), Steward skips the research step, so give it this context yourself.
It helps to know which tables hold your key business entities, which metrics your team talks about most, and any business-specific terminology, but you don't need all of that up front. Steward can help you discover what's in your data and what's worth modeling. Start with one model, your most important business entity, rather than building everything at once.
Tip
Describe what you want in business terms, not technical ones. Say "I need to track customer lifetime value" rather than "create a metric with a SUM expression joined across two tables."
The composer¶
The composer at the bottom of the Steward panel is where you write requests. It has these controls:
| Control | What it does |
|---|---|
| Plan mode | Steward drafts a plan for you to review before it changes anything. |
| Context | Shares the page or entity you're viewing with Steward. |
/ |
Inserts a saved prompt. |
@ |
Mentions a model, metric or glossary term. |
| Attach files (paperclip) | Adds files for Steward to read. |
| Stop | Stops Steward while it's working. |
Plan mode¶
Turn on Plan mode when you want to check that Steward understood your intent before it does anything, especially for larger changes.
While plan mode is on, Steward can still investigate. It searches and lists entities, inspects tables, reads analyst conversations and attachments, asks you questions, and consults its guides. It doesn't run queries, metrics or SQL, propose or apply semantic-layer edits, or create or change AI Analysts. Those steps go into the plan instead.
When the plan is ready, it appears in a Proposed plan card. You can add an optional note, then choose:
| Action | Result |
|---|---|
| Approve | Steward carries out the plan. Plan mode turns off. |
| Edit | Change the plan text, then select Save (or Cancel edit). Plan mode stays on. |
| Keep planning | Steward revises the plan. Plan mode stays on. |
| Cancel | Discards the plan. Plan mode turns off. |
Plan mode is off when you start a new session. Each session keeps its own plan mode setting, so reopening a session from History restores it.
Context¶
The Context toggle (Show Steward what you're looking at) shares the page or entity you have open with Steward. It can share an AI Analyst, Model, Metric, Glossary term, Data connection or Catalog connection. Context is on each time the Steward panel loads. Turn it off if you don't want Steward to see the page you're on.
Saved prompts such as /quickstart, /expression and /validate-model work on "the model I have open" or "the entity I have selected", so keep Context on when you use them.
Saved prompts and mentions¶
- Type
/at the start of an empty composer to open the saved prompts menu, then keep typing to filter it. See Steward memory and saved prompts to create your own. - Type
@anywhere in your message to mention a model, metric or glossary term. Steward searches your semantic layer as you type, and inserts the name you pick.
Steer or stop Steward¶
While Steward is working, the composer shows The Steward is working — send a message to steer it…. Send a message to redirect Steward without waiting for it to finish, or select Stop to cancel. A turn you stop is marked Stopped.
Attach files¶
You can give Steward documents to work from, such as a metric specification, a data dictionary or a glossary export. Steward can read them and, for example, create or update semantic-layer entities from their contents.
To attach files, select Attach files (the paperclip) in the composer, or drag files onto the composer and drop them when Drop files to attach appears.
| Supported formats | Size limit |
|---|---|
| PDF (.pdf), Markdown (.md, .markdown), Text (.txt), CSV (.csv), JSON / YAML (.json, .yaml, .yml) | 8 MB per file |
How Steward works with attachments:
- Long files. Steward reads long files in sections and can search within a file for the parts it needs.
- PDFs. Steward reads the PDF's text. For a scanned PDF with no text layer, it falls back to text recognition (OCR) by the language model.
- One message only. A file belongs to the message you attached it to. Steward can't read it from a later message, so attach the file again if you need it later in the session.
- Imports. When you ask Steward to import definitions from a file, it checks what already exists, prefers updating existing entities over creating duplicates, and tells you about rows it can't map. Its changes go through the usual approvals.
Attached files are listed under your message in the session, with their size. To download one, select its download button (Download filename).
Review and approve changes¶
Every change Steward wants to make to the semantic layer is shown before it's applied, as long as Apply edits is set to Ask first (the default).
By default, Steward asks for your approval before it:
- applies semantic-layer edits (Apply edits),
- creates or changes an AI Analyst (Write AI Analyst),
- runs SQL against your warehouse (Run SQL query).
Each request appears as a card headed Steward wants to followed by the action, in place of the composer. Select View details to see what will change, for example the Before and After values of each semantic-layer edit, or the SQL statement. Then choose one of these:
- Accept applies the change.
- Accept, don't ask again in this chat applies it, and lets this action run without asking for the rest of the session.
- Request changes declines it, so you can tell Steward what to do differently.
Other tools, including Save to memory, run without asking by default. Members with Edit in the Workspace can change which tools run automatically, ask first or are blocked, under Steward settings (the cog icon) → Tools: Always allow, Ask first or Always deny. See Approvals and tool permissions.
Warning
Steward can make mistakes. Review its proposed edits before you approve them. See Accuracy and limitations.
Answer Steward's questions¶
When Steward needs more information, the composer is replaced by a Steward asks for input card. Questions can be yes/no, a list of Suggestions to choose from (sometimes Select all that apply), or free text (Type my own).
- Answer each question, using Next and Back to move between them.
- Select Review to check your answers under Review your answers.
- Select Submit All.
If Steward asks only one question, answer it and select Submit.
To carry on without answering, select Skip questions.
Follow Steward's progress¶
- Steps. Under each reply, Steps expands to show the tools Steward used, such as Search semantic layer or Run metric. See the tool reference below.
- To-dos. For longer jobs, Steward keeps a checklist in the To-dos panel above the composer, with its progress (for example, 2/5).
Undo changes¶
Steward records the changes it applies in each session, so you can undo them from the session itself:
- Rollback to here on one of your messages undoes the changes Steward made from that point on, and removes that message and everything after it from the conversation.
- Rollback all changes undoes every semantic-layer and analyst change Steward made in the session and clears the conversation.
- Select one of your earlier messages to edit it and submit it again. You choose Revert to also undo Steward's changes from that point, or Don't revert to keep them.
Rollbacks can't be undone. See Rolling back Steward changes.
Common workflows¶
Building your first model¶
Point Steward at a table and ask it to help you model it:
"Help me create a model from my customers table"
"I have an orders table, what should I model from it?"
Steward examines the table structure and suggests dimensions and measures based on what it finds. It writes descriptions in business-friendly language, identifies obvious measures (counts, sums of numeric columns), and proposes sensible filters, such as excluding deleted or test records.
With a model open and Context on, use /quickstart to have Steward fill in missing descriptions and display names and suggest measures for the whole model at once.
If your data connects to other tables, Steward can suggest relationships. Mention which other models exist, or ask it to look for foreign keys.
Review what Steward suggests, then refine. The first pass doesn't need to be perfect.
Creating metrics¶
Describe the business outcome you want, not the formula:
"Create a metric for average order value"
If the metric needs measures or relationships that don't exist yet, Steward identifies the gaps and can create them. For metrics that span multiple models, it works out the joins, and it suggests default filters, such as excluding cancelled orders from revenue.
Steward may ask clarifying questions, such as "How do you define an acquired customer?" or "Should this include refunded orders?" Your answers become the metric's business logic.
You don't need to know SemQL: Steward writes the expression. If the result isn't quite right, refine it in the conversation: "Actually, this should only count orders over $50" or "Can we break this down by region too?" You can also start with /create-metric.
Writing expressions¶
When you're editing a dimension, measure, filter or metric and need help with the syntax, use /expression or describe what you want:
"How do I calculate a percentage of successful orders?"
Steward knows which columns and measures are available, and it can run a query to check that an expression returns what you expect. If a metric's expression fails validation, select Fix with Steward next to the error. For a dimension, measure or filter, use /expression or describe the problem to Steward.
If you come across an expression you don't understand, ask Steward to explain it:
"What does this expression do?"
You can also ask Steward to find similar expressions in your semantic layer, such as an existing percentage calculation or filtered count, so you can follow the same approach.
Validating and improving models¶
Use /validate-model to have Steward review the model you have open for common issues:
- Dimensions or measures missing descriptions
- Naming inconsistencies
- Expression errors or edge cases
- Missing relationships to other models
- Best practice violations
Use /relationships to find missing connections between models. Steward analyzes your semantic layer, suggests relationships that might be missing, and explains why.
Steward can also do bulk fixes: "Add descriptions to all dimensions that are missing them" or "Rename all date fields to use the _at suffix."
Tips for working with Steward¶
Give context. "We're a logistics company, shipments are our core entity" is more useful than assuming Steward already knows. Use consistent business terminology.
Iterate in small steps. Several short messages work better than one giant prompt. Let Steward propose something, then refine it: "That's close, but exclude test accounts" or "Actually, let's break this down by region instead."
Correct misunderstandings directly. If Steward gets something wrong, say so: "No, that's not what I meant. By 'active' I mean customers who ordered in the last 90 days." Steward adjusts.
Break big tasks into sessions. Instead of "build my entire semantic layer," start with "help me model my customers table." Steward remembers context within a session, and it also reads a persistent memory at the start of every session. To view or edit it, open Steward settings (the cog icon) → Memory. Changes are recorded in the audit log. Start a new session for each new task, and put context you want every session to have in memory. See Steward memory and saved prompts.
Quick commands reference¶
These built-in saved prompts are available in every Workspace. They're shortcuts for common requests: you can always describe what you want in plain language instead.
| Command | What it does |
|---|---|
/init |
Set Steward up with context about your business |
/quickstart |
Quickly flesh out the model you have open: descriptions, display names and suggested measures |
/expression |
Help write an expression for the selected entity |
/create-metric |
Create a new metric step by step |
/validate-model |
Review the selected model for issues and improvements |
/relationships |
Find relationships that might be missing |
You can customize these prompts and add your own. See Steward memory and saved prompts.
Steward tool reference¶
The Steps list under each reply names the tools Steward used:
| Tool | What it does |
|---|---|
| List models, List metrics, List glossary terms | Lists entities in the semantic layer |
| Search semantic layer | Searches across the semantic layer |
| List data sources | Lists the Workspace's data connections |
| Inspect warehouse tables | Looks at warehouse tables and their columns |
| List AI Analysts | Lists the Workspace's AI Analysts |
| Write AI Analyst | Creates or changes an AI Analyst (asks first by default) |
| Search analyst conversations, Read analyst conversation | Finds and reads recent AI Analyst conversations |
| Run SemQL query, Run metric | Queries data through the semantic layer |
| Run SQL query | Runs a read-only SQL query on a warehouse (asks first by default) |
| Propose edits | Drafts semantic-layer changes |
| Apply edits | Applies semantic-layer changes (asks first by default) |
| Ask a question | Asks you for input |
| Read attachment | Reads a file attached to the current message |
| Search the web | Searches the web (not available on air-gapped deployments) |
| Update to-do list | Updates the To-dos checklist |
| Save to memory | Adds to Steward's memory |
| Present plan | Shows the Proposed plan card in plan mode |
| Consult a guide, Search guides, Read a guide | Uses Steward's built-in guides |
| Note an issue | Records a diagnostic note about a product problem Steward ran into |
Usage¶
If your organization has a message limit, each message you send to Steward counts toward it, and AI Analyst conversations share the same limit. This includes messages you send to steer Steward and replies in plan mode.
Feedback and reporting problems¶
- To rate a reply, select Good response or Bad response under it. You can add an optional comment. Steward may also ask How's this conversation going? in a banner.
- To report a problem, select Report a problem (the bug icon) in the Steward header, describe what went wrong, and select Send report. If a session is open, it's attached to your report. This button appears only when problem reporting is enabled for your deployment.
Troubleshooting¶
| Message or symptom | What it means | What to do |
|---|---|---|
| Steward says the Workspace is read-only | You don't have the Edit capability in this Workspace. | Ask someone with Manage members and access for the organization, or a Workspace member who holds both Edit and Manage members, to give you Edit in this Workspace. |
| Memory or Tools is missing from Steward settings | These need the Edit capability in the Workspace. | Ask someone with Manage members and access for the organization, or a Workspace member who holds both Edit and Manage members, to give you Edit. |
| Your organization has reached its message limit — contact your admin to upgrade. | Your organization has used its message allowance, if it has a limit. | Contact your administrator. |
| Chat needs an LLM endpoint. Ask your administrator to connect one, then try again. | No language model endpoint is set up for your organization. | Ask a member with Manage inference to set one up in Settings → Inference. |
| Your organization's own LLM endpoint didn't answer. An administrator can check it in Settings → Inference. | Your organization uses its own LLM endpoint, and it didn't respond. | Ask a member with Manage inference to check the endpoint. |
| Actian Inference couldn't answer. Please try again in a moment. | The language model service didn't respond. | Wait a moment and send your message again. |
| Unsupported file type or File too large (max 8 MB) | The file isn't a supported format, or it's over 8 MB. | Convert or split the file, then attach it again. |
| Could not upload filename | The upload failed, so Steward won't see the file. | Attach the file again on your next message. |
/init doesn't research your company |
Web search isn't available on your deployment. | Describe your company and data in the conversation, or add it to memory yourself. |