How to Set Up Cube for Agentic Analytics

What is Cube and Why It Matters Now

Cube is an open-source semantic layer for data analytics. It connects to your database, lets you define measures and dimensions in YAML or JavaScript, and exposes those definitions via REST, GraphQL, and SQL APIs to any BI tool, application, or AI agent that needs them.

The core idea is consistency. Without a semantic layer, every analyst and every AI prompt re-derives the same metric from raw SQL, often getting slightly different answers depending on how the joins are written. Cube forces one canonical definition per metric. When you change how "monthly revenue" is calculated, every dashboard and every agent query inherits the update automatically.

In February 2026, Gartner named Cube a Representative Vendor in its Market Guide for Agentic Analytics. The guide's key finding: "Semantic and policy alignment is foundational for effective agentic analytics" and predicted that 60% of agentic analytics projects relying solely on Model Context Protocol (MCP) without a semantic layer would fail by 2028. That finding has driven a surge of interest from ops teams and analysts who want AI agents querying their data reliably, not hallucinating metrics.

This guide covers setting up Cube Core (the open-source version) locally with Docker, connecting it to a Postgres database, generating a first data model, and running your first natural-language query through the Cube D3 agentic interface.

Prerequisites

Before starting, you need:

• Docker Desktop installed and running (version 24 or later)
• A Postgres database with at least one table of real data — a local Postgres instance works fine
• Node.js 18 or later (used to run the Cube CLI for model generation)
• About 15 minutes

If you do not have Postgres running locally, you can spin one up in Docker: docker run --name pg-demo -e POSTGRES_PASSWORD=demo -e POSTGRES_DB=analytics -p 5432:5432 -d postgres:16. Load a sample dataset like the classic orders table with a quick seed script before continuing.

Step 1: Run Cube with Docker

Create a new empty folder for your Cube project:

mkdir cube-demo && cd cube-demo

Then start Cube with a single Docker command:

docker run -p 4000:4000 \
  -p 15432:15432 \
  -v ${PWD}:/cube/conf \
  -e CUBEJS_DEV_MODE=true \
  cubejs/cube

Port 4000 is the Cube API and the Developer Playground UI. Port 15432 is Cube's SQL API, which lets tools like Metabase or any Postgres-compatible client query Cube as if it were a database.

Open http://localhost:4000 in your browser. The Developer Playground loads.

Step 2: Connect Your Database

The Playground prompts you to select a data source. Choose PostgreSQL. Enter your connection details:

• Host: host.docker.internal (if Postgres is running on your Mac or Windows host machine) or the container name if it is in the same Docker network
• Port: 5432
• Database: your database name
• Username / Password: your Postgres credentials

Click Apply and Cube writes a cube.js environment file to your project folder. From this point on, Cube is reading live from your Postgres instance.

For production deployments, these credentials go into environment variables (CUBEJS_DB_HOST, CUBEJS_DB_NAME, CUBEJS_DB_USER, CUBEJS_DB_PASS) in a .env file or your secrets manager. Never hardcode them.

Step 3: Generate Your Data Model

Cube can inspect your database schema and generate a starter data model automatically. In the Developer Playground, go to Schema and click Generate. Select the tables you want to include. Cube produces YAML files in the model/cubes/ folder of your project.

A generated model for an orders table might look like this:

cubes:
  - name: orders
    sql_table: public.orders

    measures:
      - name: count
        type: count
      - name: total_revenue
        sql: amount
        type: sum

    dimensions:
      - name: status
        sql: status
        type: string
      - name: created_at
        sql: created_at
        type: time

This is a starting point, not a final definition. The important step is renaming measures to match how your business actually uses the terms and adding any calculated metrics your team cares about. A measure called total_revenue with clear SQL behind it is the kind of canonical definition that prevents the metric drift problem described earlier.

Edit the YAML directly in your project folder. Cube hot-reloads model changes without a restart.

Step 4: Test Queries in the Playground

Back in the Playground, click Build to run your first query. You can select measures and dimensions from a dropdown and Cube generates the underlying SQL, executes it, and shows results in table or chart form.

The SQL API (port 15432) lets you connect Metabase, Tableau, or any Postgres-compatible client directly. In Metabase, add a new database connection of type PostgreSQL, point it at localhost:15432, and use the same credentials as Cube's SQL API. From that point, Metabase sees all your Cube cubes as database tables.

You can also query via the REST API directly:

curl -G http://localhost:4000/cubejs-api/v1/load \
  --data-urlencode 'query={"measures":["orders.total_revenue"],"dimensions":["orders.status"]}' \
  -H 'Authorization: YOUR_API_TOKEN'

The API token is set with CUBEJS_API_SECRET in your environment.

Step 5: Enable Agentic Queries with Cube D3

Cube's D3 layer, announced in mid-2025 and now generally available, adds AI agents on top of the semantic model. The key difference from ad-hoc LLM-to-SQL approaches is that D3 agents query the semantic model, not the raw database. That means the agent cannot invent a revenue calculation — it must use the total_revenue measure you defined.

For Cube Cloud users, D3 activates from your account dashboard under Agentic Analytics. The free tier includes a limited number of agent requests per month, enough to test the feature with a real dataset.

Once enabled, the D3 interface lets you type questions like "What was total revenue by status last month?" and the agent resolves the query against your semantic model, returns results, and explains how it arrived at the answer. Because the semantic layer enforces consistent definitions, the answer from a D3 agent matches the answer from your Metabase dashboard using the same Cube connection.

For self-hosted Cube Core, D3 is not yet available as open source. The agentic features require Cube Cloud or an enterprise license.

What This Setup Gives You

After completing these steps, you have a working semantic layer that:

• Serves consistent metric definitions to any BI tool via SQL, REST, or GraphQL
• Generates SQL from your cubes automatically with caching built in
• Provides a foundation for AI agents to query data without hallucinating metrics

The next practical step is defining more cubes for the tables your team queries most, adding role-based access control for row-level security, and connecting your primary BI tool to the SQL API.

If you want to skip the model-building phase and get to data questions immediately, VSLZ lets you upload a CSV or connect a data source and ask questions in plain English without writing YAML or configuring infrastructure — useful for ad-hoc analysis while your Cube semantic layer is still taking shape.

Practical Notes

Cube performs best as a long-running service, not a per-query container. For production, deploy it as a dedicated service with a Redis instance for caching (CUBEJS_CACHE_AND_QUEUE_DRIVER=redis). The default in-memory cache works for development but does not persist across restarts.

Keep your cube YAML files in version control. Model changes that redefine a measure should go through a review process the same way schema migrations do — a change to total_revenue SQL affects every dashboard and every agent query that uses it.