Atlas User Guides

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:

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

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:

How It Works

When you ask a question, Atlas processes it through a multi-step pipeline:

1. 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.
2. Schema Fetch — The AI fetches available cubes and measures from the data model.
3. Query Generation — Converts your question into a semantic query.
4. Validation — Ensures the query is valid and all referenced members exist.
5. Execution — Runs the query with your security context (RBAC, RLS).
6. Results — Displays data with automatic visualizations.
7. 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.

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

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:

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

Creating a Dashboard

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.

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)

Best Practices

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).

Visual Model Builder

The Visual Builder supports two modes for creating data models:

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.

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.

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)

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.

The workflow supports a progression: Upload → Analyze → Curate → Publish → Make available in Insights. Datasets can be personal (private) or workspace-scoped (shared).

Uploading Files

1. Click "Upload CSV" button
2. Select a CSV file from your computer
3. Configure options: Dataset Name and Storage Type (Temporary or Persistent)
4. 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.

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".

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.

Example Questions

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

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

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

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

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.

Single Sign-On (SSO)

SSO lets users authenticate via your identity provider (IdP) such as Okta or Azure AD. This is an Enterprise feature.

1. Open Settings → Security → SSO tab
2. Enter your IdP configuration (OIDC or SAML)
3. Run the connection/test workflow
4. 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.

1. Open Settings → Security → MFA Policy tab
2. Choose the enforcement level (optional vs required)
3. Save the policy
4. Verify that users are prompted to configure MFA on next sign-in

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

Application Issues

Query Issues

Display & Schema Issues