Atlas User Guides

Everything you need to get started with BlackOptic Atlas — from asking your first question to building dashboards, modeling data, and managing your workspace.

Data Modeling

llm.txt

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 TypeDescriptionEditable
Base ModelsAuto-generated from database tablesRead-only (visibility only)
Published CubesUser-created overlays/extensions of base modelsFully editable
ViewsUser-created semantic views (curated projections across cubes)Fully editable

Visual Model Builder

The Visual Builder supports two modes for creating data models:

FeatureCustom CubeView
PurposeCustomize a single cube or define missing joinsCombine multiple cubes for a unified query surface
Max cubes on canvas2Unlimited
Define joinsYes (for missing FK relationships)No (uses existing join paths)
Hide membersYesYes
Calculated fieldsYesYes

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

  1. Navigate to Admin → Data Models and click "Visual Builder"
  2. Ensure "Custom Cube" mode is selected
  3. Add a base model from the left panel
  4. Select which dimensions and measures to include
  5. Optionally add calculated fields
  6. Preview the generated code and click "Save & Compile"

Creating a View

  1. Select "View" in the mode toggle
  2. Add multiple cubes to the canvas
  3. Select fields from each cube to include
  4. Optionally add calculated fields
  5. Preview the generated view definition
  6. 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 ActionDescriptionAvailable For
ExplainGet an explanation of selected code or the entire cubeAll file types
Fix errorsAutomatically fix compilation errorsPublished, View
Add fieldAdd a new dimension or measurePublished, View
Suggest joinsFind cubes that can be joined with the current onePublished, View
VisibilityToggle the cube's visibility from the LLMAll file types

Note

Base models are read-only in the AI Assistant. The panel displays a READ-ONLY badge and suggests opening the Published model instead for edits.

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)