Getting Started
Overview
Welcome to BlackOptic Atlas — an AI-powered Business Intelligence platform that lets you explore your data through natural language conversations and create beautiful dashboards without writing SQL.
Atlas connects to your existing databases (PostgreSQL, MySQL, Snowflake, and more), builds a semantic understanding of your data, and lets anyone on your team ask questions in plain English to get instant insights, charts, and reports.
Quick Start Guide
Once your workspace is set up and you're signed in, here's how to start exploring your data:
1. Ask a Question
Navigate to Chat and type a natural language question like "Show me the main metric by month for the last 6 months"
2. Explore Results
View data in interactive tables, see automatic chart visualizations, and read AI-generated summaries.
3. Create a Dashboard
Click "Add to Dashboard" on any query result, choose a dashboard, and arrange widgets with drag-and-drop.
4. Export Data
Click "Export" to download data as CSV or JSON. Use filters to narrow down results before exporting.
Next Steps
- Read the Chat Interface Guide to learn how to ask effective questions
- Explore the Dashboards Guide to create and manage dashboards
- Check out CSV Datasets to upload and analyze spreadsheet data
- Review Roles & Permissions to understand access control
Chat Interface
Asking Questions
The chat interface accepts natural language questions about your data. Simply type your question and press Enter or click Send. Here are some example questions by category:
Trends & Time Series
- "Show me the main metric over the last 6 months"
- "Compare this quarter vs last quarter"
- "Break down the trend by week"
Top-N & Rankings
- "Top 10 items by value"
- "Which categories contribute the most?"
Breakdowns & Segments
- "Total by category"
- "Distribution by status"
- "How does the metric vary by region?"
Entity Lists (SQL Mode)
- "List records where status is pending"
- "Show all items created in the last 30 days"
How It Works
When you ask a question, Atlas processes it through a multi-step pipeline:
- Cache Check — The backend looks for a matching question in the per-tenant query cache. If found, it re-executes the cached query for fresh data.
- Schema Fetch — The AI fetches available cubes and measures from the data model.
- Query Generation — Converts your question into a semantic query.
- Validation — Ensures the query is valid and all referenced members exist.
- Execution — Runs the query with your security context (RBAC, RLS).
- Results — Displays data with automatic visualizations.
- Summary — Provides a natural language explanation of the results.
During execution, you'll see ephemeral status messages like "Loading schema", "Executing query", and "Generating chart". These disappear once the task is complete. The final response includes a clean explanation, inline charts, a data table, and expandable technical details (Cube query and SQL).
Follow-up Questions
You can ask follow-up questions that reference prior context. The AI maintains context from the last ~10 Q&A pairs in your session.
Example Conversation
Initial: "Show me the main metric by category"
Follow-up: "Now break that down by month"
Follow-up: "Just for one category"
Uploading Files
You can upload files directly from the chat interface using the paperclip icon (📎) next to the input box. Click it to open the file picker, select a file, and it's automatically uploaded and attached to the current chat session.
Supported file types: PDF, DOCX, TXT, MD, CSV, JSON, XLSX, XLS
Note
You can also manage context through the Manage Context dialog (book icon 📖). Attach Spaces or individual files from your Knowledge Base to give the AI additional context for answering your questions.
Visualizations
The AI automatically suggests the best visualization based on your data:
| Data Pattern | Chart Type |
|---|---|
| Time series | Line chart |
| Categorical breakdown | Bar chart |
| Single aggregate value | KPI card |
| Proportions | Pie chart |
You can switch chart types from the inline results card. Available types include Bar, Line, Area, Pie, Doughnut, and Scatter. Customize X-Axis, Y-Axis, Series grouping, and toggle data labels on or off.
Tips for Better Results
✅ Be Specific
Instead of "Show the metric"
Try "Show the total by month for the last quarter"
✅ Include Time Ranges
Instead of "Value by category"
Try "Value by category for the last 6 months"
✅ Use Business Terms
Instead of "Money made" (ambiguous)
Try "Total revenue" (matches measure names)
✅ Add Filters
Instead of "List all records"
Try "List records with status = completed from last week"
Error Recovery
Dashboards
Creating a Dashboard
From Chat
- Ask: "Create a dashboard showing key metrics"
- AI generates relevant widgets
- Dashboard opens automatically
Manual Creation
- Navigate to Dashboards section
- Click "New Dashboard"
- Enter name and description
- Add widgets
Adding Widgets
From Query Results: Run a query in chat, click "Add to Dashboard", select a dashboard and position, and the widget appears on the dashboard.
Manual Widget Creation: Open a dashboard, click "Add Widget", configure the query and visualization, then position and resize as needed.
Layout & Filters
- Drag & Drop — Reposition widgets by dragging
- Resize — Drag widget corners to resize
- Grid System — Automatic alignment and spacing
- Responsive — Adapts to screen size
Apply filters to all widgets simultaneously: click "Add Filter", select a dimension (e.g., Date Range, Region), choose filter values, and all widgets update automatically. Clicking a chart element adds a quick filter chip. Filter state is encoded in the URL for shareable links.
Dashboard Copilot
Use the Copilot panel on the right side of any dashboard to explain, build, and operate dashboards with AI assistance.
| Mode | What It Does |
|---|---|
| Explain | Ask what the dashboard shows, what changed, and what's driving results. Answers are grounded in current widgets and filters. |
| Build | Create or update charts/metrics with a plan + diff preview before applying. If you don't have edit access, propose changes and copy a diff to share. |
| Operate | Run widget health checks (schema mismatches or query errors), refresh widgets, export the dashboard, and open the sharing workflow. |
Sharing & Export
- View Link — Share a read-only dashboard link
- Export — Download dashboard as PDF or image
- Embed — Embed dashboard in other applications (coming soon)
Note
edit_dashboards permission and a Pro or Enterprise plan.Best Practices
Design
- • Group related metrics together
- • Use consistent chart types
- • Include date range filters
- • Add descriptive titles
Performance
- • Limit to 10–15 widgets
- • Use filters to narrow scope
- • Separate by audience
Organization
- • Use descriptive names
- • Create by topic/audience
- • Archive unused dashboards
Data Modeling
Overview
Admins and Data Modelers can manage the semantic data model through multiple interfaces: the Visual Model Builder (no-code canvas), the Code Editor with AI Assistant, and button actions (generate schemas, compile, delete).
| Schema Type | Description | Editable |
|---|---|---|
| Base Models | Auto-generated from database tables | Read-only (visibility only) |
| Published Cubes | User-created overlays/extensions of base models | Fully editable |
| Views | User-created semantic views (curated projections across cubes) | Fully editable |
Visual Model Builder
The Visual Builder supports two modes for creating data models:
| Feature | Custom Cube | View |
|---|---|---|
| Purpose | Customize a single cube or define missing joins | Combine multiple cubes for a unified query surface |
| Max cubes on canvas | 2 | Unlimited |
| Define joins | Yes (for missing FK relationships) | No (uses existing join paths) |
| Hide members | Yes | Yes |
| Calculated fields | Yes | Yes |
When to use Custom Cube: Single cube customization (hide fields, add calculated measures), define missing joins between two tables, or two-cube join scenarios.
When to use View: Combine multiple cubes into a unified query surface, create curated data surfaces, or leverage existing join paths.
Creating a Custom Cube
- Navigate to Admin → Data Models and click "Visual Builder"
- Ensure "Custom Cube" mode is selected
- Add a base model from the left panel
- Select which dimensions and measures to include
- Optionally add calculated fields
- Preview the generated code and click "Save & Compile"
Creating a View
- Select "View" in the mode toggle
- Add multiple cubes to the canvas
- Select fields from each cube to include
- Optionally add calculated fields
- Preview the generated view definition
- Save & Compile — join paths must exist between all cubes
Calculated Fields
Add custom dimensions or measures using the Calculated tab in the right panel. Choose from three calculation types:
- Single Column — Apply an operation to one column (UPPER, EXTRACT YEAR, etc.)
- Two Columns — Combine two columns or use constants (Subtract, Add, Multiply, Divide, Days Between, Concatenate, Coalesce, etc.)
- Advanced SQL — Write raw SQL expressions for power users (note: bypasses the portability layer)
Calculated fields appear in the Members tab with colored highlights (blue for dimensions, green for measures) and a sparkle icon. You can toggle them on/off without deleting them, and create intermediate calculations as building blocks for complex expressions.
AI Code Editor
The Code Editor features an integrated AI Assistant panel that provides context-aware assistance while you edit schema files. It understands your current file, content, selection, compilation errors, and cube type.
| Quick Action | Description | Available For |
|---|---|---|
| Explain | Get an explanation of selected code or the entire cube | All file types |
| Fix errors | Automatically fix compilation errors | Published, View |
| Add field | Add a new dimension or measure | Published, View |
| Suggest joins | Find cubes that can be joined with the current one | Published, View |
| Visibility | Toggle the cube's visibility from the LLM | All file types |
Note
Visibility Controls
Control what cubes and fields are visible to the LLM and users. Navigate to Admin → Data Models → View / Edit, hover over any cube, and click the eye icon to toggle visibility (green = visible, orange = hidden). Click Compile to apply changes.
- Visibility preferences survive base model regeneration
- You can hide base models without modifying them
- Hidden cubes have public: false set, making them invisible to the API and LLM
- Use cases: security (hide sensitive data), declutter (faster LLM responses), development (hide WIP cubes)
CSV Datasets
Overview
Upload CSV files for quick ad-hoc analysis without creating permanent semantic models. CSV datasets can optionally be made available in Insights after review. This feature is ideal for quick analysis of spreadsheet exports, one-time data exploration, testing queries before integrating data sources, and analyzing data that doesn't need permanent storage.
| Mode | Description |
|---|---|
| CSV Dataset (tabular) | Managed in CSV Analysis for profiling, curation, and ad-hoc exploration. Can be explicitly enabled for Insights. |
| CSV Knowledge (KB) | Ingested as text for retrieval/citations; never becomes a Cube dataset. |
The workflow supports a progression: Upload → Analyze → Curate → Publish → Make available in Insights. Datasets can be personal (private) or workspace-scoped (shared).
Uploading Files
- Click "Upload CSV" button
- Select a CSV file from your computer
- Configure options: Dataset Name and Storage Type (Temporary or Persistent)
- Click "Upload"
Supported formats: .csv files with auto-detected delimiters (comma, semicolon, tab, pipe) and encoding (UTF-8, Latin-1, etc.). Headers are expected in the first row.
| Storage Tier | Retention | Quota Impact | Limits |
|---|---|---|---|
| Temporary | 7 days (auto-deleted) | None | 200 MB total, 10 datasets/user |
| Persistent | Configurable (default 365 days) | Counts toward quota | 50 datasets/user |
Analyzing Data
Click Analyze on any dataset to open the analysis page with a three-column layout:
- Left Sidebar (Query History) — Shows your current session and previous queries. Start new analyses, edit, or delete previous queries.
- Center (Chat Interface) — Conversational chat with your data. Ask questions in plain English, edit previous questions, regenerate answers.
- Right Panel (Details) — Results tab with auto-generated charts, SQL query, and data table. Data Preview tab shows first 10 rows.
When you open a dataset, the system automatically generates quick insights: total records, numeric summaries, date ranges, and top categories. The AI converts your questions to SQL and executes them using DuckDB, an in-memory analytical database optimized for fast analytical queries.
Curating & Publishing
Curating: Click "Curate" to rename columns, override data types, hide columns, add descriptions, and create calculated fields using SQL expressions. The curation recipe is saved as JSON and applied whenever the dataset is queried.
Publishing: Click "Publish" to make your dataset available to the workspace. Choose visibility (Private, Shared, or Tenant-wide). Published datasets can be made available in the main Insights Chat and Dashboard widgets by an Admin or Data Modeler via "Make available in Insights".
Advanced Analytics
Overview
Atlas includes an optional Python Analysis feature that enables complex analytics beyond standard queries. The AI assistant automatically determines when to use Python analysis based on your question — no configuration needed from your side.
| Question Type | Query Method |
|---|---|
| "What is the total metric by category?" | Standard Query |
| "Show me all records in a specific group" | SQL Query |
| "Who reports directly or indirectly to Carol?" | Python Analysis |
| "What's the 90th percentile of a numeric field?" | Python Analysis |
Example Questions
Recursive Hierarchies
- "Which employees report (directly or indirectly) up to Carol?"
- "Show me the entire org chart under the VP of Engineering"
Statistical Analysis
- "What is the 90th percentile salary by department?"
- "Show me the correlation between two numeric fields"
Complex Transformations
- "Calculate the running total of a metric by month"
- "Show me the month-over-month growth rate"
Tips & Limitations
Python Analysis runs in a secure sandbox with code validation, network isolation, resource limits, and data access control. Be specific about relationships for hierarchy queries and explicit about statistical measures.
- Cross-source queries are not supported — data must come from a single source
- Results are based on data at query time (not real-time)
- Very large result sets may be truncated
- If Python Analysis is disabled, the AI will suggest alternatives or ask you to contact your administrator
Spaces
Overview
Spaces are a unified knowledge center for organizing files and context. Use them to group related documents and attach a Space to a chat session so the AI assistant can reference that context when answering your questions.
- Upload files — Add files to your Space (PDF, DOCX, TXT, MD, CSV, JSON, XLSX, XLS)
- Link existing Library files — Add files from your Knowledge Base into a Space
- Attach a Space to chat — Use "Manage Context" to attach one or more Spaces to the current session
User Flows
Create a Space
- Go to Spaces
- Click "Create Space"
- Choose scope: Workspace (shared) or Personal (private)
- Name the Space (e.g., "Finance")
Workspace Spaces require the manage workspace Spaces permission (Admins by default).
Add Files & Attach to Chat
- Open a Space → Files tab
- Use "Upload" to add new files or "Add Files" to link existing Library files
- In Chat, click the book icon (Manage Context)
- Select the Spaces tab and attach your Space
BI Tool SQL API
Overview
Atlas exposes a SQL API (via Cube's PostgreSQL Wire Protocol) so external BI tools like Power BI, Tableau, and Metabase can query the semantic layer using a standard PostgreSQL connection.
Connection Parameters
| Parameter | Local Dev | Deployed |
|---|---|---|
| Host | localhost | Depends on environment (K8s service, load balancer, etc.) |
| Port | 15432 | Depends on environment |
| User | cube (default) | Configured per deployment |
| Password | Value of CUBEJS_SQL_PASSWORD | Strong password required |
| Database | db (if required by tool) | Configured per deployment |
Note
checkSqlAuth() is implemented for your deployment.Roles & Permissions
Overview
Atlas uses role-based access control (RBAC) to control which pages a user can access, which actions they can take, and which data they can see (Row Level Security / Column Level Security).
Plan gating: Essentials includes predefined roles only (Admin, Analyst). Pro/Enterprise adds Viewer + Data Modeler roles, and enables Custom Roles, RLS, and CLS.
Predefined Roles
| Role | Description | Tier |
|---|---|---|
| Admin | Full access — manage users/roles, data sources, data models, billing, and audit logs | All tiers |
| Analyst | Use chat and dashboards; upload/analyze CSV datasets; cannot manage users/roles | All tiers |
| Data Modeler | Manage data models and datasources; use chat to validate; cannot manage users | Pro+ |
| Viewer | View dashboards and use chat for Q&A; cannot edit dashboards or pin charts | Pro+ |
To manage roles, open Admin → Roles. Pro/Enterprise tenants can create Custom Roles with any combination of permissions.
Row & Column Security
Row Level Security (RLS) Pro+ — Filters data rows based on the viewer's role attributes. Configure row-scope rules in Admin → Roles (e.g., only allow region = East).
Column Level Security (CLS) Pro+ — Hides specific cubes/fields from users who should not see them. Configure allowed cubes/fields (field allowlist) in Admin → Roles.
Billing & Plans
Overview
Atlas uses seat-based billing with three tiers: Essentials, Pro, and Enterprise. Workspace admins can view and manage billing from Settings → Billing or via the user menu → Plan & Billing.
The billing page is organized into four tabs: Overview (plan summary, quick stats), Plans (compare and manage), Usage (AI credits, seats, storage), and Payment (payment method and billing details).
Free Trial
Pricing Tiers
Essentials
$5 / user / mo
Min 5 users · Max 10 users
- ✓ Agentic chat + streaming
- ✓ AI charts & insights
- ✓ Dashboards + exports
- ✓ CSV upload & analysis
- ✓ Visual Builder
- ✓ 200 AI credits/user/mo
Pro
$10 / user / mo
Min 10 users · Max 50 users
- ✓ Everything in Essentials
- ✓ Code Editor + AI Copilot
- ✓ Cross-source joins
- ✓ Dashboard sharing
- ✓ Custom roles + RBAC
- ✓ RLS + CLS + Audit logs
- ✓ 1000 AI credits/user/mo
Enterprise
Custom
Custom limits
- ✓ Everything in Pro
- ✓ BYO-key (own LLM keys)
- ✓ SSO (OIDC/SAML)
- ✓ MFA / 2FA policies
- ✓ SLA + dedicated support
- ✓ Custom limits
AI Credits
Atlas AI (hosted) uses credits for AI-powered features. Most actions cost 1 credit (chat, copilot, single chart). Advanced actions like dashboard AI generation cost 2 credits. Monthly allowance = billable seats × credits per user. Credits reset at the start of each billing period.
| Tier | AI Credits Included |
|---|---|
| Trial | 100 (one-time, no reset) |
| Essentials | 200 / user / month |
| Pro | 1,000 / user / month |
| Enterprise | Custom |
When credits are exhausted, AI features pause but non-AI features remain fully available. View usage in Plan & Billing → Usage tab.
Security Settings
Single Sign-On (SSO)
SSO lets users authenticate via your identity provider (IdP) such as Okta or Azure AD. This is an Enterprise feature.
- Open Settings → Security → SSO tab
- Enter your IdP configuration (OIDC or SAML)
- Run the connection/test workflow
- Save and have a test user sign in
MFA / 2FA Policies
MFA policies let admins require additional authentication (e.g., TOTP) for users. This is an Enterprise feature.
- Open Settings → Security → MFA Policy tab
- Choose the enforcement level (optional vs required)
- Save the policy
- Verify that users are prompted to configure MFA on next sign-in
Audit Logs
Overview
Audit Logs help tenant admins review key security, governance, and data-access events — who did what, when, and from where. This is a Pro+ feature. Navigate to Admin → Audit Logs.
Browsing & Filtering
The audit log table shows: Time, Category (auth, data, admin, content), Event type, User (email), Target (resource), and IP address.
- Filter by category, event type, user ID, and start/end date
- Click "View" to open the event detail modal (full JSON payload)
- For query.executed events, filter values are redacted for security
- Export filtered results as CSV or JSON
Troubleshooting
Application Issues
Error: "DATASOURCE_ENCRYPTION_KEY is required but not set"
Generate an encryption key with the provided script, add it to your environment configuration, and restart the backend service.
API Keys Show "Unreadable"
The encryption key may have changed or been lost. Restore the original key or re-save provider keys via the API. Always backup your environment configuration securely.
Cannot Connect to Data Sources
Check if the database password is unreadable (encryption key changed), verify network connectivity, and confirm database credentials are correct.
Query Issues
| Issue | Solution |
|---|---|
| No results found | Verify data exists for your query period, check role access, try broader filters or date ranges |
| Query timeout | Add filters to narrow the query, reduce date range, try during off-peak hours |
| Access denied | Data restricted by your role — contact admin for access |
| Join path error | Missing foreign key relationship — ask admin to add it in Data Model → Foreign Keys |
| Schema compilation error | Data model has errors — ask admin to recompile in Admin → Data Model → Generate Schemas |
| No data model found | Data model hasn't been generated yet — ask admin to generate schemas |
| Query generation failed | Rephrase your question more clearly, break complex questions into simpler ones |
Display & Schema Issues
| Issue | Solution |
|---|---|
| Charts not displaying | Verify data has numeric values for measures, check dimensions are appropriate for chart type, try table view |
| Export taking too long | Add filters to reduce dataset size, break export into smaller chunks |
| Schema compilation failed | Check for syntax errors in custom cubes, verify all referenced fields exist |
| Custom cube not visible | Verify compilation was successful, check cube visibility settings, ensure user has permission |
| Join errors | Verify join columns exist in both models, check relationship type, ensure base models are compiled |