Key concepts¶

Names in bold match the labels in the app, and most sections link to the page that covers the feature in detail.

If you used an earlier version of AI Analyst, see If you used an earlier version at the end of this page for the terms that changed.

Organization and Workspaces¶

Organization¶

Your organization is your company's account in AI Analyst. Billing, Seats, message usage, members, the organization logo and the chart theme belong to the organization, never to a single Workspace.

You can belong to more than one organization. You switch between them from the switcher at the top of the sidebar (see Switching organization and Workspace).

Workspace¶

A Workspace is a separate space inside your organization. Each Workspace has its own:

Models, Metrics, Glossary terms and Tags (its semantic layer)
AI Analysts
Conversations and Artifacts
Steward memory and tool permissions

Workspace content is a hard boundary: nothing you create in one Workspace can be read from another. Workspaces cannot be nested.

Data connections are the exception. By default a connection belongs to the organization and is attached to Workspaces, so the same connection can serve several Workspaces. A Workspace can also have a connection that is private to it. See Data connections.

Members with Manage organization create, rename and delete Workspaces in Settings → Workspaces. See Workspaces.

Default Workspace¶

Every organization has one default Workspace, marked Default in Settings → Workspaces. When you apply a preset, its Workspace Capabilities are given in the default Workspace only (see Capability presets).

You can delete the default Workspace while another Workspace exists. The oldest remaining Workspace then becomes the default. You can't delete the organization's last Workspace.

Warning

Deleting a Workspace permanently deletes everything in it: its Models, Metrics, Glossary terms, AI Analysts, API keys, private connections and uploaded files. It also deletes any organization connection that is attached only to that Workspace, together with its credentials. You must type the Workspace name to confirm.

Switching organization and Workspace¶

Open the switcher at the top of the sidebar. It shows your organization name and, below it, your current surface (Explorer or Studio), preceded by the Workspace name when you can open more than one Workspace.

Organizations lists every organization you belong to. Picking another one reloads the app in that organization. You might be asked to sign in again. You can't create an organization from the switcher.
Workspaces appears only when you can open two or more Workspaces. It lists only the Workspaces where you hold a Capability. If you can open just one Workspace, the switcher doesn't name it.

When you switch Workspace, the app returns you to the home page of the surface you are on. Your choice is remembered in this browser only.

If you haven't chosen a Workspace in this browser, for example in a private window, AI Analyst opens the organization's default Workspace if you hold a Capability there. Otherwise it opens the Workspace where you were first given access. A link from a notification can switch you to the organization and Workspace the notification is about.

Access: Capabilities, presets and surfaces¶

Capabilities¶

A Capability is a single permission that a member holds, either for the whole organization or in one Workspace. In the app, each Capability is a switch you turn on or off. Capabilities only add access. There is no "deny" Capability.

Organization-level permissions

Capability	What it allows	Opens
Manage organization	Manage organization settings, security, audit logs, API keys and Workspaces.	Studio and Explorer
Manage members and access	Invite, remove and set Capabilities for any member, in any Workspace.	Studio and Explorer
Manage billing	Manage the organization's billing and subscription.	Explorer only
Manage inference	Choose the organization's LLM and Embedding endpoints. See Inference.	Explorer only

Workspace Capabilities (held separately in each Workspace)

Capability	What it allows	Opens
Chat	Converse with Analysts and use saved prompts in this Workspace. Grants Explorer access.	Explorer
Edit	Author Analysts, the semantic layer, connections, and Steward configuration in this Workspace. Includes Chat. Grants Studio access.	Studio and Explorer
Manage members	Add, remove, and set Capabilities for members of this Workspace only. Includes Chat. Grants Studio access. You can give only the Capabilities you hold there.	Studio and Explorer

Organization-level permissions are set in Settings → Members → Edit access…. Workspace Capabilities can also be set in Settings → Workspaces → Members. See Members.

No access without a Workspace Capability¶

No one reaches a Workspace automatically, organization administrators included. To open a Workspace's AI Analysts and content, you need a Workspace Capability in it. If you hold none there, the Workspace doesn't appear in your switcher.

Members with Manage organization still see every Workspace in Settings → Workspaces, so they can rename or delete it. Seeing it there doesn't let them open its content.
Members with Manage members and access can give any member, themselves included, Capabilities in any Workspace.
Creating a Workspace doesn't give you any Capability in it. To work in a new Workspace, someone with Manage members and access must give you a Capability there. The Administrator preset includes it.

Capability presets¶

A preset is a one-click set of Capabilities that you choose in Edit access… → Select preset.

Preset	Capabilities it sets	Surfaces
Administrator	All four organization-level permissions, plus Edit and Manage members in the default Workspace	Studio and Explorer
Editor	Edit in the default Workspace	Studio and Explorer
Viewer	Chat in the default Workspace	Explorer
Billing contact	Manage billing only	Explorer, opening on billing settings

When you edit an existing member, the menu also offers No access (see No access). It shows Custom when a member's Capabilities don't match any preset.

A preset sets the switches once. A member never "is" a preset: after you apply one, you can change any Capability on its own.

Default preset for new users¶

Availability

Who can do this: members with the Manage organization capability.
Plan: Included only in plans that enable Enterprise SSO.

When your organization uses Enterprise SSO with JIT membership, Settings → Administration → Security has a setting called Capabilities to give new users. AI Analyst applies this preset when someone signs in for the first time and your identity provider doesn't name a preset. Changing it doesn't change existing members. See Security.

Explorer and Studio¶

AI Analyst has two areas, called surfaces. Which ones you get depends on your Capabilities.

Surface	Who uses it	What's in it	Who gets it
Explorer	Business users	New task, Inbox, Artifacts, Scheduled Insights, and your conversations (Starred, Conversations, Shared with me)	Anyone who holds at least one Capability
Studio	Data teams	AI Analysts, Models, Metrics, Glossary, Connections, and the Steward panel	Members with Edit or Manage members in the active Workspace, or Manage organization or Manage members and access

A few rules to know:

Workspace Capabilities count only in your active Workspace. If you have Edit in one Workspace and only Chat in another, you have Studio in the first and lose it when you switch to the second.
Where you land after sign-in. You land in Studio if you have it, otherwise in Explorer.
Switching surface. Open the switcher at the top of the sidebar and choose Explorer or Studio. It lists only the surfaces you have.
Members who can't chat. A member who holds only Manage billing or Manage inference gets an Explorer without conversations. Billing contacts open on the billing settings. Others open on their profile.
Small screens. Explorer works on a phone. Studio needs a desktop-sized window: below that, Studio pages show Studio needs a bigger screen with a Go to Explorer button.

To get started on each surface, see Getting started in Explorer and Getting started in Studio.

Settings¶

Settings looks the same from both surfaces. In Studio, open Settings in the Manage group of the sidebar. In Explorer, open the account menu at the bottom of the sidebar and choose Profile, Security or Notifications.

Everyone sees Profile, Security and Notifications for their own account. The sections under Administration and Environment appear only when your Capabilities include what that section needs. For example, Members needs Manage members and access, and Billing needs Manage billing.

Note

The Members item in the Studio sidebar is visible to every Studio member. If you don't hold Manage members and access, it shows "You need Manage members permission to view this page."

Membership and Seats¶

Pending invitation¶

When you invite someone by email from Settings → Members, they appear under Pending invitations until they accept. You can Resend or Revoke an invitation. Invitation emails come from the identity provider and can take up to 10 minutes to arrive.

Pending member¶

Availability

Who can do this: members with the Manage members and access capability.
Plan: Included only in plans that enable Enterprise SSO.

In an organization that uses Enterprise SSO, you can add someone whose email address is on your SSO domain before they ever sign in. They're listed under Waiting for first SSO sign-in. No email is sent. Their access starts the first time they sign in through SSO, and they hold a Seat until then.

No access¶

No access means a member holds no Capability anywhere in the organization. They keep their sign-in and their membership, but they can't open Explorer or Studio. They see a page titled No product access yet with a Sign out button.

Setting someone to No access takes effect straight away:

Their Seat is released.
Their sign-in sessions are ended, which signs them out of every organization they belong to.

You can't set yourself to No access, and the organization must keep at least one member who can manage access.

Warning

If your identity provider assigns a preset to a member, it applies that preset again at the member's next sign-in, replacing changes made here. To remove that member's access for good, remove it in your identity provider.

Seat¶

A Seat is how billing counts people. It isn't a permission.

Every member who holds any Capability holds a Seat. Pending members hold one too.
A Seat is released when a member is set to No access or removed.
When all Seats are taken, new in-app invitations are refused with "This Organization has no spare Seats…". Members who already hold a Seat keep working.
Sign-ins through your identity provider (SCIM or JIT membership) are still admitted when all Seats are taken, so your identity provider integration keeps working.
People who talk to an AI Analyst in Slack or Microsoft Teams without an AI Analyst account are channel guests. A channel guest takes a Seat the first time they ask a question, and the question is refused if no Seat is free. Guests who hold a Seat are listed under Channel guests in Settings → Members.

See Billing & Usage.

AI Analysts and conversations¶

AI Analyst¶

An AI Analyst (an Analyst, for short) is a named assistant with its own avatar, instructions and data access. Your data team builds and tests it in Studio, under AI Analysts. Business users talk to it in Explorer. It answers by running queries against the semantic layer and producing charts, tables and reports.

A new Analyst can't query any Model or see any Glossary term until someone gives it access. An Analyst can use a Metric only if it has access to every Model that Metric uses. See Creating an AI Analyst and Access Management.

Deployment and audience¶

An Analyst is either Deployed or Not deployed. A Not deployed Analyst is visible only to Studio users, who can still edit and test it.

To deploy, open the Analyst and choose Deploy → Explorer. The Deploy to Explorer dialog offers:

Studio users only: not visible in Explorer (this undeploys the Analyst).
Specific users: only the people you add.
Everyone: every member of the Analyst's Workspace. The hint reads "All organization members", but the audience is the Workspace.

Members with Edit in the Workspace can always use every Analyst in it, deployed or not. Changes to an Analyst's instructions and data access apply straight away. They aren't frozen when you deploy.

Conversation¶

A conversation is one thread with one Analyst. In Explorer, you start one with New task, and it's listed under Conversations.

You can share your conversation with Only me, Everyone in this organization (in practice, every member of the Workspace) or Specific people. There is no public link.
People you share it with can read it but can't send messages. Members with Edit in the Workspace are the exception: they can continue any conversation in it.
Only the owner can delete a conversation. Deleting can't be undone and removes it for everyone it was shared with.

See Sharing.

Artifact¶

An Artifact is a chart, table or report that an Analyst produces in a conversation. You can save it to Artifacts in Explorer, where you can rename, star, archive and share it. Archived Artifacts can always be restored.

When you open a saved chart or table, its query runs again against the current semantic layer and live data, so you see fresh results. If the query can't run, you see the saved snapshot instead. Reports don't re-run.

Artifact sharing offers Only me, Anyone in this organization (in practice, every member of the Artifact's Workspace) and Specific people. Each person you add under Specific people gets an Inbox item. See Artifacts.

Report¶

A Report is a single Artifact made of blocks such as headings, paragraphs, lists, KPI cards, charts, tables and grids. It grows in place as the Analyst updates it, and a version is saved after each change. See Reports.

Inbox and Scheduled Insights¶

Inbox in Explorer collects items from your AI Analysts and system alerts, such as Artifacts that others share with you and the results of scheduled runs. Scheduled Insights are recurring analyses that run on a schedule and deliver findings when their instructions say to. A run can put a finding in your Inbox, and can email you. See Inbox and Scheduled Insights.

Steward¶

The Steward is the assistant in Studio that builds and maintains your semantic layer through chat. Open it from the Steward tab in the panel on the right of Studio. Each Workspace has one Steward.

By default, the Steward shows you each change it wants to make and waits for your approval. Under Tool permissions, you can set each tool to Always allow, Ask first or Always deny. A tool set to Always allow makes changes without asking.

The Steward Inbox collects alerts, suggestions and insights about your semantic layer. See Using Steward and Steward Inbox.

Channel¶

Availability

Who can do this: members with the Edit capability in the active Workspace.
Deployment: Not available on air-gapped self-managed deployments.

A channel is Slack or Microsoft Teams, where business users talk to an Analyst. Each channel is bound to exactly one Analyst, and binding a Not deployed Analyst deploys it. The Analyst answers only when someone @mentions it in a channel. Direct messages to the bot aren't supported.

People without an AI Analyst account can ask questions as channel guests. They can use only the data of the bound Analyst. Someone whose verified email address matches a member of your organization is treated as that member. See Messaging Apps.

The semantic layer¶

The semantic layer is the business meaning your Analysts use to query your data. Each Workspace has its own. See Semantic layer overview.

Term	What it is
Model	A semantic view of warehouse data, built from one table or a SQL query. You can't change a Model's data connection or its table or SQL source after you create it. See Models.
Dimension	A descriptive attribute used to group and filter, such as region. Written in your warehouse's SQL dialect. See Dimensions.
Measure	An aggregated number, such as total revenue. Written in your warehouse's SQL dialect. See Measures.
Filter	A named, reusable condition on a Model's dimensions, written in SemQL. With Apply to every query on, it always applies and the Analyst can't turn it off. See Pre-defined Filters.
Relationship	A join from one Model to another. See Relationships.
Metric	A named KPI built on one primary Model, optionally joined to other Models through that Model's relationships. It has a headline SemQL expression, an optional time dimension with allowed time grains, and a chosen set of dimensions, measures and filters. Its filters come from the primary Model, and that Model's always-applied filters always apply. See Metrics.
Glossary term	A business term with a Definition, synonyms, tags, an optional parent term, and mappings to Models, dimensions, measures, filters or Metrics. Each name must be unique in the Workspace, so use names such as "Finance Revenue" under a parent term. See Glossary.
Tag	A label from one Workspace-wide list shared by Models and Glossary terms. Tags can decide which Models and terms an Analyst can use, and that access updates as tags change.
SemQL	The SQL-like language for querying the semantic layer. It names Models, dimensions, measures and filters, never physical tables, and is compiled into each warehouse's SQL dialect. See Semantic SQL (SemQL).

Tip

Tag-based access works in both directions. If an Analyst uses Models with any of these tags, tagging a Model adds it to that Analyst. If an Analyst uses All models except these tags, tagging a Model removes it.

Data connections¶

A data connection links a Workspace to a warehouse, a catalog or uploaded files. See Connect a data source.

Type	Who manages it	Where it can be used
Organization connection (the default)	Members with Edit in any Workspace it's attached to. If Restrict connection management is on in Settings → Administration → Security, only members with Manage organization.	Every Workspace it's attached to. Members with Manage organization choose which Workspaces.
Private to this Workspace	Every member with Edit in that Workspace	Only that Workspace. Other Workspaces can't see or use it.
Uploaded files	Members with Edit in that Workspace. If Restrict connection management is on, only members with Manage organization.	Only the Workspace they were uploaded to. They can never be shared.

Restrict connection management doesn't apply to private connections. You only see the connections attached to your active Workspace.

To make a private connection available to other Workspaces, a member with Manage organization, working in the connection's Workspace, chooses Share with organization. The connection becomes an organization connection and stays attached to its Workspace, so nothing built on it changes. You can't make it private again.

Deployment and inference¶

Actian SaaS and self-managed deployments¶

AI Analyst is delivered in two ways:

Actian SaaS: Actian runs the service for you.
Self-managed deployment: your organization runs AI Analyst in its own cloud, data center or on a single host, using a Helm chart or a Docker Compose bundle from Actian. Your operator supplies secrets and runs upgrades.

Connected and air-gapped¶

A self-managed deployment is either connected or air-gapped. This is set for the whole deployment, not per organization. On a self-managed deployment, inference comes from endpoints that your administrator or your organization provides.

An air-gapped deployment makes no outbound calls to Actian or to outside services. On an air-gapped deployment:

Slack, Microsoft Teams and other integrations that need an outside service aren't available.
The in-app Docs and Support chat aren't available.
Report a Bug saves your report on the installation. Nothing is sent to Actian. An administrator includes saved reports in a diagnostic export for Actian.

Inference¶

Inference is the language model that answers conversations (Chat) and the embedding model that powers semantic-layer search (Search). Settings → Inference shows where each one comes from:

Source	Meaning
Actian Inference	Models hosted through Actian. Available on Actian SaaS, where it is the default.
Provided by your administrator	The default endpoint that the operator of your self-managed deployment configured.
Your organization's own endpoint	Your organization's own OpenAI-compatible endpoint (customer inference).
None	No endpoint is available.

If Chat has no endpoint, conversations are blocked until someone with Manage inference adds one. If Search has no endpoint, search matches keywords only.

Customer inference means your organization uses its own LLM endpoint, Embedding endpoint or both, instead of the deployment's default.

Availability

Who can do this: members with the Manage inference capability (included in the Administrator preset). Members with Studio access can open Settings → Inference read-only.
Plan: Requires the Customer-hosted inference feature, shown in Settings → Usage. Without it, your organization uses the deployment's default.

Keep in mind:

An LLM endpoint must pass a Test, in which the model calls a tool, before you can save it.
If your organization's own LLM endpoint fails, the conversation turn fails. AI Analyst never falls back to another endpoint.
Saving or removing an Embedding endpoint re-indexes your semantic layer. Search matches keywords only until re-indexing finishes.

Licence¶

Availability

Deployment: Self-managed deployments only.

A self-managed deployment runs on a licence signed by Actian. It sets the licence end date, a grace period, Seats, limits and features, and applies to every organization in the deployment.

After the licence end date, Studio shows a banner with the date the grace period ends, and AI Analyst keeps working. After the grace period, product work stops, but you can still export your data through the Public API. The length of the grace period is set in each licence.

If you used an earlier version¶

Some terms changed when AI Analyst was rebuilt. The table maps earlier names, from the previous product or from earlier versions of these docs, to the current ones. For a full guide, see Moving from the previous product.

Earlier term	Current term	Where to find it now
Admin, Studio, Explorer and Billing roles	Capabilities, with the presets Administrator, Editor, Viewer and Billing contact	Settings → Members → Edit access…
Workspace roles Studio, Explorer and Manager	Workspace Capabilities Edit, Chat and Manage members	Settings → Workspaces → Members
Admins reach every Workspace	No automatic access. You need a Workspace Capability to open a Workspace.	See No access without a Workspace Capability
Agent	AI Analyst (Analyst). Some labels still say "agent", such as Agent activity in Explorer.	Studio → AI Analysts
Traces	Monitoring → Tasks and Analytics	Open an Analyst in Studio and choose Monitoring. See Monitoring.
Slack channel for alerts, under Settings > Notifications	Channel notifications (Slack or Microsoft Teams, set per Workspace), and personal email notifications	Settings → Administration → Notifications, and Settings → Notifications

A few behaviors changed along with the names:

The Administrator preset gives Workspace Capabilities only in the default Workspace.
The Billing contact preset now opens Explorer, on the billing settings.
A connection can be private to one Workspace.
Settings still groups Audit and Import / export under Environment.

If your organization was moved from the previous product by Actian, conversations moved with it can be read by the people who already had access, but nobody can send new messages in them. Start a new conversation to keep asking.

Common questions¶

Why can't I see a Workspace in the switcher? You hold no Capability in it, or you can open only one Workspace. Ask a member with Manage members and access to give you a Capability there.

Why did Studio disappear when I switched Workspace? You have Edit or Manage members in the previous Workspace but not in this one. Switch back, or ask for Edit in this Workspace.

What does "No product access yet" mean? Your account holds no Capability in this organization. The page may say you have no "Explorer or Studio role". That means you have no Capability. If you belong to another organization, use the switcher on that page to change organization. Otherwise, ask an administrator to give you access.

If you need more help, see Getting help.