# Analyst ## Overview Analyst (formerly "Aura Analyst") is an AI-powered data analyst that makes it easy to converse with the data in plain English. It is a fully managed agentic AI service built natively for SingleStore that translates natural language questions into precise SQL queries and instantly delivers insights from the databases. By removing the requirement of manually writing SQL or building complex dashboards, Analyst accelerates analytics and empowers users to uncover insights faster. Leveraging SingleStore’s Agentic AI platform, it ensures that queries are accurate, context-aware, and governed, helping teams make smarter, data-driven decisions with ease. > **📝 Note**: All queries and interactions require an active Domain context. Domains define the unit of context, data scope, and governance for Analyst. ## How Analyst Works Analyst is a fully managed agentic, multi-component AI system designed to transform natural language into reliable, actionable insights. Instead of relying on a single, monolithic model, it orchestrates a series of specialized stages, including intent interpretation, query planning, SQL generation, validation, execution, and result summarization. This modular architecture enhances accuracy, ensures control, and adapts flexibly across diverse datasets and query types. By clarifying ambiguous inputs, exposing query plans, and automatically retrying on failures, Analyst provides a more dependable experience while building user trust. Beyond running SQL, the system makes results easy to interpret through natural-language summaries and visualizations, enabling business and technical users alike to act on data with confidence. When answering a question, Analyst performs the following: 1. Interprets the question using the active domain, including schema metadata, relationships, instructions, and approved learned context. 2. Generates and validates SQL against the domain’s connected data. 3. Executes queries under domain-scoped database credentials. 4. Returns results with natural-language explanations and optional visualizations. ## Domains A **Domain** is the context service for Analyst. It acts as a knowledge base, supplying the semantic and structural framework required to interpret questions accurately, generate the right SQL, and deliver governed insights. Users with the “Agent Domain Owner” permission can configure Domains by selecting relevant clusters, databases, and tables. They can enhance Domains with custom instructions, business-specific formulas, or logic that Analyst applies when answering questions.Once configured, a Domain abstracts the complexity of raw schemas. Users interact with a curated, context-rich view of the data, making analytics more accurate, consistent, and accessible. A Domain includes the following: * Connection to a SingleStore cluster and access to a selected set of databases and tables. * Schema metadata and descriptions that help Analyst understand the data model. * Join relationships used when generating multi-table SQL. * Instructions and learned context that encode business rules, vocabulary, and preferences. * Access controls that determine who can use or manage the Domain. Domains are dynamic. As data changes and new business requirement emerges, users can continuously refine them. Each update enhances the context service, ensuring that insights remain reliable, governed, and immediately actionable. ## Create a Domain Once Analyst is enabled, select **Create domain**. In the **Create Domain** dialog: | **Domain Details** | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Enter the name of the domain. | | **Description** | Enter the domain description. | | **Connect Data** | | | **Connection** | Select theSingleStoreclusterthe domain connects to.Specifying aclusterallows connecting theSingleStoredatabases referenced in the domain.SingleStorerecommends creating a newclusterwith a read-only database attachment for Analyst to maintain clarity and separation of workloads. | | **Select tables** | Select the tables from theSingleStoredatabases. | Select **Create** to create the domain for Analyst. > **📝 Note**: Analyst keeps the cluster active as hourly metadata collection prevents the cluster from remaining idle for more than one hour. ## Configure an Existing Domain When a Domain is created, Analyst performs the following: * Fetches the data accessible to the Agent Domain Owner and uses that as the starting scope. * Uses AI to infer table and column descriptions. * SingleStore recommends that owners review the description and modify it as needed. * Creates a domain-scoped database user `_auraanalyst` with `SELECT` permissions to the tables selected in the Domain. All queries run by Analyst within a Domain are executed as the `_auraanalyst` user. A user can be granted Domain-level access even without having privileges on the underlying databases or tables referenced by the Domain. This allows any user with access to the Domain to query the underlying databases. A user may be a Domain **User** or Domain **Owner** regardless of other organization-level roles. A user can receive Domain-level permissions even if they are an organization member without any role grants ("roleless"). However, these permissions cannot grant or imply elevated privileges on the underlying databases. > **📝 Note**: Domain owners must manage Domain roles and access settings to align with their organization’s governance policies. To configure an existing domain, enable **Creator Mode**. Refer to [Creator Mode](https://docs.singlestore.com/#section-id235777130915387.md) for more information. ## Analyst Access Controls SingleStore Aura defines four RBAC (role-based access control) roles for Analyst: * **Organization Level Controls**: * **Aura Creator**: Provides the ability to install and uninstall Analyst. * **Agent Domain Owner**: Provides the ability to create and manage domains. > **📝 Note**: Domain creation is limited to the tables accessible by the "Agent Domain Owner". * **Domain Level Controls**: * **Owner**: Provides the ability to manage and access a given domain. > **📝 Note**: Domain creation is limited to the tables accessible by the "Owner". * **User**: Provides the ability to use the Domain and ask questions in natural language and receive responses. ## Creator Mode **Creator Mode** provides the configuration interface for Analyst. It is intended for organization owners and Domain owners who configure and manage Domains. Creator Mode is organized into three areas: | **Area** | **Purpose** | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | **Context Engine** | Define what Analyst knows about the Domain. Manage business rules, learned context, the semantic layer, and reusable trained queries. | | **Accuracy** | Monitor answer quality through recorded conversations and user feedback. | | **Admin** | Manage the Domain's operational configuration, including usage insights, programmatic access, permissions, and settings. | Creator Mode also provides the following: * A Domain selector for switching among Domains you manage. * A draft and published versioning model for Context Engine changes, so you can build and publish updates without affecting live users. * A preview chat for testing questions against a Domain's configuration while editing it. Creator Mode does not replace the end-user chat experience. End users continue to ask questions in Analyst chat. Use Creator Mode to configure, refine, and manage Domains, enabling Analyst to provide accurate and reliable responses. ## Context Engine **Context Engine** defines what Analyst knows about the Domain. It includes the following configuration options: * **Business Rules** * **Learned Context** * **Semantic Layer** * **Trained Queries** ## Business Rules Business Rules provide Domain-level guidance that Analyst uses to answer questions accurately. Use them to define custom instructions, background knowledge, assumptions, or business logic that might not be obvious from the underlying data. Analyst applies these rules when interpreting questions, determining response style and constraints, and generating SQL. To add a business rule, enter your context in the **Business Rules** field, and then select **Save**. Business Rules can encode the following: * Preferred metrics, formulas, and naming conventions. * Filters or assumptions that must always apply (for example, excluding test accounts). * Define tone and response preferences. * Domain vocabulary and how business terms map to tables or columns. ## Learned Context The system automatically learns contexts from user questions and interactions. Learned context captures recurring facts, clarifications, and patterns that may improve future answers. Learned context is not applied automatically without review. Domain owners can approve, reject, edit, or delete existing learned contexts. The following are the context states for the learned contexts: * **Pending**: Learned contexts that have been automatically generated by the system but have not yet been reviewed by a Domain owner. These insights are awaiting approval or rejection. * **Approved**: Learned contexts that have been reviewed and approved by a Domain owner. Only approved contexts are actively used by Analyst to answer questions and generate SQL queries. * **Rejected**: Learned contexts that have been reviewed and rejected by a Domain owner. Owners can filter by review state and update existing items as domain knowledge evolves. ## Semantic Layer The Semantic Layer allows you to review and enhance schema metadata and includes relationship management capabilities. The purpose of Semantic Layer is to help Analyst reason over the data model and write correct SQL joins. It has two tabs: **Database** and **Relationships**. ## Database The **Database** tab lists all tables and columns in the Domain along with auto-generated descriptions that help Analyst understand the data model. Domain owners can edit and refine these descriptions to improve accuracy. From the **Database** tab, you can manage tables in the Domain and their descriptions: * Add more tables to the Domain by selecting **Add**. Tables can be added from the cluster connected to the Domain. * To edit the table description, select the ellipsis (three dots), and then select **Edit**. * To delete the table, select the ellipsis (three dots), and then select **Delete**. * In the **Table** column, select the table to view and edit the description of each column of the table. ## Relationships The **Relationship** tab lists each discovered or manually added relationship with the following columns: * **From**: The source table and column. * **Type**: The cardinality of the relationship. * **To**: The target table and column. * **Source**: Whether the relationship was generated by the crawler or added manually. * **Status**: Whether the relationship is currently applied to the Domain. A relationship crawler automatically discovers join relationships between tables using schema analysis and LLM inference, assigning each relationship a confidence score between 0.0 and 1.0. You can also create relationships by selecting source and target tables and columns, specifying the following cardinality and saving entries individually or in bulk: * **> for many-to-one** * **< for one-to-many** * **- for one-to-one** * **<> for many-to-many** Manually created relationships are labeled accordingly. To add a relationship, select **Add**. In **Add table relationship**, enter or select the following: * **Left Table**: Select a table from the list. * **Right Table**: Select a table from the list. * **Join Condition**: Select the columns from each table to create a join condition. * **Type**: Select the cardinality type. * **Description** (Optional): Enter the description. Select **Save Relationship** to save the table relationship. To edit or delete a relationship, select the ellipsis (three dots) for a relationship, and then select **Edit** or **Delete**, respectively. ## Trained Queries Trained Queries store SQL patterns that Analyst can reference when answering questions. They are useful for the following: * Defining key metrics and formulas in reusable SQL. * Capturing frequently asked questions with known, good query patterns. * Teaching Analyst proven, domain-specific approaches to common analytic requests. Trained Queries work with Business Rules and Learned Context to give Analyst a complete picture of the Domain. Business Rules describe intent and policies in natural language, Learned Context captures approved facts and clarifications from previous questions, and Trained Queries provide concrete SQL examples that Analyst can reuse. They improve answer accuracy and consistency across similar questions by working together. ## Accuracy The **Accuracy** page monitors answer quality through user feedback. It includes the following configuration option: * **Feedback** ## Feedback Feedback reviews recorded Analyst conversations and user feedback to monitor quality and identify areas for improvement. On this tab: * View the question, rating, reason, and comment of the response. Select the question to view Analyst’s response. * Monitor response quality, review user feedback, and identify areas for improvement. Conversation capture is controlled in **Settings**: * When **Record conversations for review** is enabled, the conversation history associated with the Domain are recorded under Feedback. * When recording is disabled, Feedback primarily reflects questions that received explicit user feedback. Feedback closes the loop between end-user feedback and Domain improvement tasks in Learned Context, Semantic Layer, and Trained Queries. ## Admin The **Admin** page manages the operational configuration of the Domain, including usage insight, programmatic access, permissions, and settings. It includes the following configuration options: * **Usage** * **API Keys** * **Access Controls** * **Settings** ## Usage Usage summarizes how the Domain is being used. It provides usage and feedback visibility for the selected Domain over a selected time range. It includes the following: * **Questions**: Total number of user questions in the selected time range. * **Feedback**: Total number of recorded feedback events in the selected time range. * **Active Users**: Number of distinct users who asked at least one question in the selected time range. * **Question Volume**: A time-series chart shows user questions over the selected time range, bucketed by day. * **Feedback Trend**: A time-series chart shows positive and negative feedback over the selected time range, bucketed by day. * A per-user activity breakdown of questions and feedback in the selected time range. ## API Keys Create and manage API keys used for authenticating requests to the Analyst API. API keys enable programmatic access to Analyst capabilities in external applications, workflows, and experiences. Use API Keys when you need governed, domain-bounded access to natural-language analytics outside the Analyst chat. For more information on endpoint, authentication, and request formats, refer to the [Analyst API](https://docs.singlestore.com/cloud/ai/analyst/analyst-api.md). ## Access Controls Access Control provides the ability to assign roles, set permissions, and control who can access the Domain. View all the users or teams and their roles in this tab. To share access to the Domain with a user or a team, select **Add**. In the **Share \** dialog, select **User** or **Team**, select the access role, and then select **Save**. To remove access for any **User** or **Team**, select **Remove Access** in the access role of the selected user or team. > **📝 Note**: Inherited roles cannot be modified. ## Settings Settings holds Domain identity and operational configuration. It includes the following: * **Name**: Specifies the Domain name. Select the Edit icon to update it. * **Description**: Update the Domain description. * **Cluster**: The SingleStore cluster the Domain connects to. * **Record conversations for review**: When enabled, Analyst saves all conversations for the selected Domain to **Feedback**. If this setting is disabled, only questions with user feedback are captured in **Feedback**. * **Dashboards**: When enabled, the system allows users to create and view dashboards. * **Delete Domain**: Delete a Domain when it is no longer needed. ## Versioning Creator Mode uses a versioned publish model so context changes can be developed safely and tracked over time. Instead of a single published state, each Domain maintains a complete history of published versions as well as an optional working draft. | **State** | **Meaning** | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Published version** | An immutable snapshot of the Domain configuration captured when the domain is published. Each publish produces a new version with a sequential version number, and Analyst uses the most recently published version to answer questions. | | **Draft** | A working copy created from the current published version and owned by the Domain owner. Draft edits remain isolated from users until they are published, and can be refined, previewed, or discarded at any time. | ## Version history Every publish is preserved as a distinct version, giving owners an auditable record of how a Domain's context has evolved. From the version history, an owner can select any prior version to perform the following actions: * **View**: Inspect the configuration of that version and view how it differs from other versions. * **Test**: Run the selected version in the preview side panel to evaluate its behavior against real questions before making any change. * **Restore**: Publish a previous version as the live configuration. Viewing and testing a prior version are non-destructive. They cannot affect what end users view and are intended for exploring and evaluating history. ## Restore a Version Restoring a prior version publishes it as the newest version in the history and makes it the live configuration. After a restore, Creator Mode shows the differences between the restored version and the previously live version, which makes the net effect explicit. ## Edit and Publish New Versions Published versions are immutable and are never edited in place. To modify the live configuration, select **Edit**, which creates a draft from the current published version. Make changes within that draft, and publish it to produce the next sequential version, which becomes the live configuration. Each owner can maintain only one draft per Domain at a time. Starting a new draft while one already exists discards the existing draft. Discarding a draft abandons its unpublished edits without affecting any published version. > **📝 Note**: Versioning applies to Context Engine. Changes made to Business Rules, Learned Context, and Semantic Layer through the draft workflow. Trained Queries write directly to the published configuration; Trained Queries do not currently support drafts. ## Interacting with Analyst Once a domain is created and configured, you can ask any data related questions to Analyst using natural language. To start a conversation, select the desired domain in the chatbox. Domains can be switched at any time during a conversation. > **📝 Note**: All queries and interactions require an active Domain context. Within a conversation, the following features can be accessed: * Multi-turn follow-up questions that reuse session context. * **Thoughts block**: View how Analyst approached to provide the insights as a response including the SQL queries executed. * **Left panel controls**: * View the chat history. * Start a new session. * Delete an existing session. * **Feedback**: Your feedback enables a human-in-the-loop system that continuously improves results. * Improve accuracy over time: Feedback helps refine how queries are interpreted and answered to deliver more reliable and complete responses for future queries. * Domain expert review: Domain owners can review query interactions to identify gaps and improve overall system performance. For a query response, use the “**Is this correct?**” option under the query result to provide feedback. * Select **Yes** (thumbs-up) if the response is correct. * Select **Needs Improvement** (thumb-down) if the response is incorrect or incomplete. When **Needs Improvement** is selected, submit feedback by selecting one of the following options: * Values look off * Missing data * Misunderstood question * Analyst made something up * Other Optionally, enter additional details in the field to describe what went wrong. > **📝 Note**: Observers can use [Monitoring](https://docs.singlestore.com/cloud/user-and-cluster-administration/cluster-health-and-performance/historical-monitoring/#section-idm33412590041948.md) and [Query History](https://docs.singlestore.com/cloud/query-data/query-tuning/query-history.md) to track queries run by Analyst, including slow-performing queries. ## Share a Chat You can share an Analyst chat with other users in your organization, enabling them to review the conversation and its associated insights. To share a chat: 1. Open a chat that includes at least one assistant response. 2. Select **Share** from the right top of the chat. 3. Copy the generated link and share it with the users who need access. > **📝 Note**: - The shared chat is a snapshot of the conversation up to the most recent assistant response at the time of sharing. It does not update if the chat continues. > - Shared chats are not public. A user can access a shared link only if the following conditions are met: > > * The user is signed in as a member of the same organization that owns the chat. > * The user has permission to use the Analyst domain associated with the chat. > - Users who do not meet these conditions see an access denied message. > - Sharing a chat link is separate from other sharing features in Analyst. It does not affect the following: > > * Saving or sharing charts to dashboards > * Domain access or domain sharing settings in **Domain settings** ## Continue a Shared Chat When a user opens a shared link, the conversation appears in **read-only** mode. To continue working from that conversation: 1. Select **Continue conversation** at the bottom of the page. 2. Analyst creates a new chat session that copies the shared conversation. New messages in this session do not affect the original chat or the shared snapshot. ## Examples ## Example 1: SaaS Product Usage Analytics This example analyzes product adoption by creating a domain focused on it, using the relevant tables from the `saas_usage` database. ![Create Domain dialog showing 'SaaS Usage Domain' name, connection deployment set to workspace-1, and four tables selected from saas\_usage database: subscriptions, support\_tickets, usage\_logs, and users. Cancel and Create buttons appear at the bottom.](https://cdn.sanity.io/images/h3bp8c98/production/1ce451f36de79cb28d231ca303a9867c91e76bcc-1752x1646.png) Once the domain is created, questions can be asked about the data. ![](https://cdn.sanity.io/images/h3bp8c98/production/32f534fb8a1f567ff4cafc714ec3269d5baa25a2-1325x1065.gif) ## Example 2: E-commerce Marketing and Campaign Analytics This example analyzes marketing product adoption by creating a domain focused on it, using the relevant tables from the `marketing_analytics` database. ![Create Domain dialog showing 'Marketing Analytics Domain' name, connection deployment set to workspace-1, and five tables selected from marketing\_analytics database. Options to cancel or create are at the bottom.](https://cdn.sanity.io/images/h3bp8c98/production/3cfdb277d14a4da9ced7940f13e48640480e574d-1762x1647.png) Once the domain is created, questions can be asked about the data. ![](https://cdn.sanity.io/images/h3bp8c98/production/b713bf3b846f3431c6b0763c5b80736ec344b2b4-1325x1065.gif) ## In this section * [Analyst API](https://docs.singlestore.com/cloud/ai/analyst/analyst-api.md) * [Analyst API Reference](https://docs.singlestore.com/cloud/ai/analyst/analyst-api-reference.md) *** Modified at: September 8, 2026 Source: [/cloud/ai/analyst/](https://docs.singlestore.com/cloud/ai/analyst/) (An index of the documentation is available at /llms.txt)