Assistant

Overview

The assistant lets your users ask questions about the dashboard in front of them, about one card, or about any data they can reach, and get answers in plain words. Every answer runs under the user's own access: the same row and column policies, semantic domain access and permissions as the dashboard itself.

Your users can:

• Ask about a dashboard or one card. From a card's ··· menu, Ask starts from exactly what that card shows, with its filters, inputs and comparisons.
• Pick up where they left off. In full page, the conversations of the last 24 hours are listed and can be reopened and continued.
• Choose where it sits. From the More menu in the panel's header: docked right, docked left, centered over the dashboard, or full page. The choice is remembered in their browser.
• Copy a conversation. Copy conversation, in the More menu, copies the questions and answers as plain text, ready to paste into a ticket or a message. Organization users also get Copy with tool calls, which adds each step the assistant took, with its input, how long it took and how many rows it returned. Results are never copied.
• Pick from suggestions. When the assistant needs a choice, it offers the options as rows to click. When several can be done together, such as which cards to add, users tick any of them and send them at once.
• Add a source. Bring a semantic dataset, or a connection, into the conversation with Add source. Only the datasets and connections the user may use are offered.

Turning it on

The assistant shows when all of these are true:

1. The project allows it. In Project settings, the AI features and Assistant switches are on (they are on by default).
2. The token enables it. Your backend mints the token with config.assistant.enabled: true.
3. The token names a user. An end user (endUserId) or an organization user. A token for a whole tenant, without a user, gets no assistant, because conversations belong to a person.

When any of these is false, the assistant does not appear at all: no button, no Ask item, and no panel.

Token options

Pass the assistant's options under config.assistant in the token request.

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  endUserId: 'user_123',
  rcls: [{ name: 'account_rows', params: { account: 'acme' } }],
  config: { 
    assistant: { 
      enabled: true, 
      name: 'Acme Insights', 
      layout: 'docked-right', 
    }, 
  }, 
};

const response = await fetch(TOKEN_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requestBody),
});

Where it appears

• The dashboard toolbar. The assistant's button sits in the toolbar. In an iframe embed, show the toolbar with showControls=true; in React, with the showControls prop.
• A card's ··· menu. Ask opens the assistant about that card, with or without the toolbar.
• Your own interface (React). Mount AssistantProvider above your toolbar and the dashboard, with the same token, and place AssistantToolbarButton wherever you like, or call toggle() from useAssistant() on your own button.

import { AssistantProvider, AssistantToolbarButton, Surfboard } from 'react-semaphor';

function AnalyticsPage({ authToken }) {
  return (
    <AssistantProvider authToken={authToken}>
      <header>
        <AssistantToolbarButton />
      </header>
      <Surfboard authToken={authToken} />
    </AssistantProvider>
  );
}

In full page, the assistant fills the dashboard's area inside your page or iframe, so your own navigation stays in place.

Fixing a missing relationship

When something your user asks for needs two datasets that your semantic model doesn't relate, the assistant says so and doesn't add a card that can't run. The reason shows as Not added, for example "Purchase Lines isn't related to Facilities in the data model, so this card can't run."

For an organization user with the Author role or above, the assistant can suggest the missing relationships, all of them in one Data model changes block. Each relationship has its own row, such as "Orders → Customers" with the keys it joins on, and the block says once which domain they're added to. Every dashboard on that domain can use them.

• Choose what to add. When there are several relationships, each row has a check box. Leave out any you don't want, then click Add relationships; the button counts what's ticked. Not now leaves the model as it is. Nothing changes until the user clicks.
• See what happened to each one. Each row shows its own result: added, already in the model (for example, someone added it on the domain page), left out, or not added with the reason. The ones that can be added are added together, even if another relationship was added in the meantime.
• Go straight on. When the assistant has said what it will do next, such as "Add the revenue table", that step appears as a button once the relationships are in. Clicking it sends those words as the user's next message.
• The assistant remembers. What the user added, left out or turned down is kept with the conversation. The assistant reads it before answering again, so it says what the model has instead of asking the same question again, and a reopened conversation shows each result.

New relationships can take up to a minute to reach every open dashboard.

Who may add a relationship follows the same rule as the semantic domain editor: an Author, Admin or Super Admin of the project's organization, with access to the domain. End users are never offered one. A token limited to one dashboard doesn't add relationships, because a relationship reaches every dashboard on its domain.

What it can reach

The assistant uses the same governed tools as the MCP server, under the user's access:

• Semantic datasets in the domains the user may open. A token limited with semanticDomainAccess keeps the assistant, and Add source, to those domains.
• SQL on your connections' tables for organization users with the Author role or above, and for end users. Their row and column policies apply to every query. A token limited to some semantic domains does not browse direct tables.

Conversations belong to one user with one set of access. If a user's policies or security parameters change, their earlier conversations are no longer shown or continued, and a new history starts.