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.

Chat Interface

llm.txt

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:

  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.

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

Uploading documents (PDF, DOCX, TXT, MD, JSON) requires the Personal Knowledge Base feature (Pro+ plans). Dataset files (CSV, XLSX, XLS) can be uploaded on all plans.

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 PatternChart Type
Time seriesLine chart
Categorical breakdownBar chart
Single aggregate valueKPI card
ProportionsPie 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

If something goes wrong, the AI automatically retries with corrections (up to 3 attempts), provides helpful error messages, and suggests query refinements.