Analytics & Visualization

Akili integrates with Apache Superset to provide self-service analytics dashboards for data products. Products with the analytics serving intent automatically make their data available in StarRocks, which Superset connects to for visualization. This guide covers the full workflow from provisioning a dashboard to embedding it in external applications.

Architecture

%%{init: {'flowchart': {'curve': 'basis'}}}%%
flowchart LR
    subgraph Akili["Akili Platform"]
        PRODUCT[Data Product] --> LAKE[Data Lake\nIceberg on Ceph]
        LAKE --> SR[StarRocks\nAnalytics Engine]
    end

    subgraph Viz["Visualization"]
        SR --> SS[Superset]
        SS --> DASH[Dashboard]
        SS --> EMBED[Embedded View]
    end

    subgraph Consumers["Consumers"]
        PORTAL[Akili Portal]
        APP[External App]
    end

    DASH --> PORTAL
    EMBED --> APP

Prerequisites

Before provisioning a Superset dashboard, ensure your data product:

1. Has a serving.yaml with intent: analytics
2. Is deployed and has at least one successful materialization
3. The StarRocks analytics catalog is configured for your tenant

# serving.yaml -- analytics intent required
serving:
  modes:
    - intent: analytics
      config:
        engine: starrocks
        materialized: true
        refresh_interval: "1h"

Provisioning a Dashboard

The akili superset provision command creates a Superset dataset and starter dashboard for your product:

akili superset provision daily-orders
# Dashboard provisioned for 'daily-orders': status=provisioned
# URL: https://superset.akili.io/superset/dashboard/42/

The provisioning process:

1. Creates a Superset dataset backed by the StarRocks table
2. Configures the dataset with column types and descriptions from output.yaml
3. Generates a starter dashboard with basic charts
4. Returns the dashboard URL

Checking Dashboard Status

akili superset status daily-orders

# As JSON
akili superset status daily-orders --json

Possible statuses:

Status	Meaning
provisioned	Dashboard is active and accessible
provisioning	Dashboard is being created
failed	Provisioning failed (check product deployment status)
deprovisioned	Dashboard has been removed

Embedding Dashboards

Superset dashboards can be embedded in external applications using guest tokens. This enables secure, read-only access without requiring users to have Superset accounts.

Generating a Guest Token

# Generate a guest token for embedding
akili superset guest-token daily-orders --user-id user-456

# Output: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# Expires at: 2026-03-16T12:00:00Z

The guest token:

• Grants read-only access to the specific product’s dashboard
• Is time-limited (configurable, default 1 hour)
• Is scoped to the tenant — no cross-tenant access
• Includes the user ID for audit trail purposes

Embedding in a Web Application

Use the Superset Embedded SDK to render the dashboard in an iframe:

<div id="superset-container"></div>

<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
<script>
  supersetEmbeddedSdk.embedDashboard({
    id: "dashboard-uuid",
    supersetDomain: "https://superset.akili.io",
    mountPoint: document.getElementById("superset-container"),
    fetchGuestToken: async () => {
      // Call your backend to generate a guest token
      const response = await fetch("/api/superset/guest-token");
      const data = await response.json();
      return data.token;
    },
    dashboardUiConfig: {
      hideTitle: true,
      hideChartControls: false,
      filters: {
        expanded: true,
      },
    },
  });
</script>

Tip

Always generate guest tokens on your server, never in client-side code. The token generation requires API authentication, and exposing your API credentials in the browser is a security risk.

Token Refresh

Guest tokens expire after their configured duration. For long-running embedded sessions, implement a token refresh mechanism:

fetchGuestToken: async () => {
  // Called automatically by the SDK when the token expires
  const response = await fetch("/api/superset/guest-token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ product: "daily-orders", userId: currentUser.id }),
  });
  const data = await response.json();
  return data.token;
}

Dashboard Lifecycle

Deprovisioning

Remove a dashboard when it is no longer needed:

akili superset deprovision daily-orders --confirm

Caution

Deprovisioning permanently deletes the Superset dashboard. Saved charts, filters, and dashboard layout are not recoverable. The underlying data in the analytics store is not affected.

Data Refresh

Dashboard data freshness depends on two factors:

1. Product materialization frequency — how often the pipeline runs (from compute.yaml schedule)
2. StarRocks refresh interval — how often StarRocks refreshes its Iceberg metadata cache (from serving.yaml refresh_interval)

For near-real-time dashboards, configure both to short intervals:

compute.yaml

compute:
  schedule: "*/15 * * * *"  # Every 15 minutes

# serving.yaml
serving:
  modes:
    - intent: analytics
      config:
        engine: starrocks
        materialized: true
        refresh_interval: "5m"

Per-Tenant Resource Isolation

Each tenant’s Superset dashboards query through a dedicated StarRocks resource group, preventing any single tenant’s queries from starving others:

Resource	Isolation Method
StarRocks catalog	Per-tenant external catalog
StarRocks resource group	Per-tenant CPU/memory limits
Superset datasets	Tenant-scoped database connection
Guest tokens	Tenant ID embedded in token claims

Related

• akili superset — full CLI reference
• Serving Layer — intent-based store routing
• Serving Configuration — configuring serving intents