Cube — Semantic Layer for Analytics
Overview
Cube (Cube Core is the self-hosted open-source part; Cube Cloud is the hosted platform) is a semantic layer: you define metrics once as code (cubes, measures, dimensions, joins, pre-aggregations), and Cube serves them to apps over a REST (JSON) API, GraphQL API and a Postgres-compatible SQL API, with caching and access control. Current release is 1.7.x (October 2026). Docs: https://docs.cube.dev.
Instructions
Data Modeling
Data model files live in model/cubes/ and model/views/ (inside the project folder mounted at /cube/conf). YAML is the format the docs recommend; JavaScript works too and is used below. Reference members of the same cube as CUBE.measure in pre_aggregations.
// model/cubes/Orders.js — Orders cube with measures and dimensions
cube(`Orders`, {
sql_table: `public.orders`,
// Pre-aggregation: materialized rollup kept in Cube Store
pre_aggregations: {
daily_revenue: {
measures: [CUBE.revenue, CUBE.count],
dimensions: [CUBE.status],
time_dimension: CUBE.created_at,
granularity: `day`,
refresh_key: { every: `1 hour` },
},
},
joins: {
Users: { relationship: `many_to_one`, sql: `${CUBE}.user_id = ${Users}.id` },
},
measures: {
count: { type: `count` },
revenue: { type: `sum`, sql: `amount`, format: `currency` },
revenue_per_user: { type: `number`, sql: `${revenue} / NULLIF(${Users.count}, 0)`, format: `currency` },
// Rolling window: trailing 7-day sum (used with a time dimension)
revenue_7d: { type: `sum`, sql: `amount`, rolling_window: { trailing: `7 day` } },
},
dimensions: {
id: { type: `number`, sql: `id`, primary_key: true },
status: { type: `string`, sql: `status` },
tenant_id: { type: `string`, sql: `tenant_id` },
created_at: { type: `time`, sql: `created_at` },
},
// Segments are named, reusable filters (queried as "Orders.completed")
segments: {
completed: { sql: `${CUBE}.status = 'completed'` },
},
});
// model/cubes/Users.js — Users cube (condensed)
cube(`Users`, {
sql_table: `public.users`,
measures: {
count: { type: `count` },
active_count: { type: `count`, filters: [{ sql: `${CUBE}.last_login_at > NOW() - INTERVAL '30 days'` }] },
},
dimensions: {
id: { type: `number`, sql: `id`, primary_key: true },
plan: { type: `string`, sql: `plan` },
country: { type: `string`, sql: `country` },
created_at: { type: `time`, sql: `created_at` },
},
});
REST API
Cube Core serves the REST API under /cubejs-api (configurable with base_path). Send a JWT signed with CUBEJS_API_SECRET in the Authorization header (the token carries the security context). Endpoints: /cubejs-api/v1/load (query), /v1/meta (model metadata), /v1/sql (generated SQL).
// src/analytics/cube-client.ts — Query the Cube REST API
const CUBE_API_URL = process.env.CUBE_API_URL!;
const CUBE_API_TOKEN = process.env.CUBE_API_TOKEN!;
type CubeQuery = Record<string, unknown>; // measures, dimensions, timeDimensions, filters, order, limit
async function cubeQuery(query: CubeQuery) {
const response = await fetch(`${CUBE_API_URL}/cubejs-api/v1/load`, { // CUBE_API_URL=http://localhost:4000
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: CUBE_API_TOKEN, // JWT; "Bearer <jwt>" is also accepted
},
body: JSON.stringify({ query }),
});
const result = await response.json();
// Long queries answer {"error": "Continue wait"}: repeat the request until data arrives
if (result.error === "Continue wait") return cubeQuery(query);
if (result.error) throw new Error(result.error);
return result.data;
}
// Example: Get monthly revenue by order status
const monthlyRevenue = await cubeQuery({
measures: ["Orders.revenue", "Orders.count"],
dimensions: ["Orders.status"],
timeDimensions: [{
dimension: "Orders.created_at",
granularity: "month",
dateRange: "Last 6 months",
}],
order: { "Orders.revenue": "desc" },
limit: 100,
});
// Example: active users by plan
const activeByPlan = await cubeQuery({
measures: ["Users.active_count"],
dimensions: ["Users.plan"],
filters: [{ member: "Users.plan", operator: "equals", values: ["pro", "enterprise"] }],
});
JavaScript SDK (React)
Build analytics UIs with @cubejs-client/core and @cubejs-client/react (both 1.7.x). Wrap the app in CubeProvider:
// src/main.tsx
import cube from "@cubejs-client/core";
import { CubeProvider } from "@cubejs-client/react";
const cubeApi = cube(process.env.CUBE_TOKEN!, { apiUrl: "http://localhost:4000/cubejs-api/v1" });
// <CubeProvider cubeApi={cubeApi}><App /></CubeProvider>
// src/components/RevenueChart.tsx — React component using Cube
import { useCubeQuery } from "@cubejs-client/react";
import { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from "recharts";
export function RevenueChart({ dateRange = "Last 6 months" }) {
const { resultSet, isLoading, error } = useCubeQuery({
measures: ["Orders.revenue"],
timeDimensions: [{
dimension: "Orders.created_at",
granularity: "month",
dateRange,
}],
});
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
const data = resultSet?.chartPivot() ?? [];
return (
<ResponsiveContainer width="100%" height={300}>
<LineChart data={data}>
<XAxis dataKey="x" />
<YAxis />
<Tooltip formatter={(value: number) => `$${value.toLocaleString()}`} />
<Line type="monotone" dataKey="Orders.revenue" stroke="#6366f1" strokeWidth={2} />
</LineChart>
</ResponsiveContainer>
);
}
Access Control
Verified JWT claims become the securityContext. For multi-tenancy, scope queries and compiled models per tenant in cube.js (or cube.py):
// cube.js — security context configuration
module.exports = {
// One compiled data model + cache per tenant
contextToAppId: ({ securityContext }) => `CUBE_APP_${securityContext.tenant_id}`,
// Called on every request: add a row-level filter
queryRewrite: (query, { securityContext }) => {
if (!securityContext.tenant_id) {
throw new Error("tenant_id is required in the security context");
}
query.filters = query.filters || [];
query.filters.push({
member: "Orders.tenant_id",
operator: "equals",
values: [securityContext.tenant_id],
});
return query;
},
};
Cube also supports declarative access_policy blocks on cubes and views (group-scoped member_level and row_level rules, plus masking); when policies exist for some groups, every other group is denied:
# model/cubes/orders.yml (excerpt)
access_policy:
- group: finance
member_level:
includes: "*"
- group: support
member_level:
includes: [count, status]
row_level:
filters:
- member: status
operator: equals
values: [completed]
If you use securityContext in contextToAppId, also set scheduledRefreshContexts so pre-aggregations refresh for each tenant.
Installation
The documented way to start is Docker Compose in an empty project folder:
# docker-compose.yml
services:
cube:
image: cubejs/cube:latest # pin e.g. cubejs/cube:v1.7.50 in production
ports:
- 4000:4000 # REST/GraphQL APIs and Playground
- 15432:15432 # Postgres-compatible SQL API
environment:
- CUBEJS_DEV_MODE=true # local only, see warning below
volumes:
- .:/cube/conf
docker compose up -d
# Open http://localhost:4000, pick your database in the wizard (it writes .env), then "Generate Data Model" (YAML or JavaScript)
Database settings go in .env: CUBEJS_DB_TYPE=postgres, CUBEJS_DB_HOST, CUBEJS_DB_NAME, CUBEJS_DB_USER, CUBEJS_DB_PASS, and CUBEJS_API_SECRET (random string used to sign and verify API JWTs). The npx cubejs-cli create scaffold still exists but the docs no longer lead with it. For production, run an API instance, a refresh worker and Cube Store (router plus workers) as in https://docs.cube.dev/cube-core/deployment.
CUBEJS_DEV_MODE=true turns off authentication on the REST and GraphQL APIs and exposes Playground with ready-made tokens. Use it only on your own machine; set CUBEJS_DEV_MODE=false anywhere else.
Examples
Example 1: Add a metrics API on top of an orders table
User request:
We have orders and users tables in Postgres. Give our frontend an API for monthly revenue by order status, with a daily rollup so it's fast.
The agent creates model/cubes/Orders.js and Users.js as above (primary keys, a many_to_one join, revenue and count measures, a daily_revenue pre-aggregation), starts Cube with docker compose up -d, and checks the model in Playground. It then verifies the endpoint with a signed token:
curl -G http://localhost:4000/cubejs-api/v1/load \
-H "Authorization: $CUBE_API_TOKEN" \
--data-urlencode 'query={"measures":["Orders.revenue"],"dimensions":["Orders.status"],"timeDimensions":[{"dimension":"Orders.created_at","granularity":"month","dateRange":"last 6 months"}]}'
The response is {"data":[{"Orders.status":"completed","Orders.created_at.month":"2026-04-01T00:00:00.000","Orders.revenue":"18420.50"}, ...]}. Measure values come back as strings.
Example 2: Make the API multi-tenant
User request:
Each customer must only ever see their own orders in the dashboard. Tokens already carry a tenant_id claim.
The agent writes queryRewrite and contextToAppId in cube.js as shown in Access Control, signs two test JWTs with different tenant_id values using CUBEJS_API_SECRET, and confirms the same query returns different rows for each. It also sets CUBEJS_DEV_MODE=false so the check is not bypassed.
Guidelines
- Semantic layer = single source of truth — Define metrics once in Cube; all apps query the same definitions
- Pre-aggregations for performance — Materialize common queries; Cube auto-selects the best pre-aggregation
- Use the Playground for exploration — Build queries visually in Cube Playground before coding them into your app
- Security context for multi-tenancy — Use
queryRewrite (or access_policy) to filter queries by tenant/group; never trust filters sent by the client
- Measures over raw SQL — Define
revenue_per_user as a Cube measure, not as raw SQL in your app
- Time dimensions for trends — Use
timeDimensions with granularity for consistent time-series queries
- Mind refresh keys — pre-aggregations refresh hourly by default; set
refresh_key to match how often the source data changes, and run a separate refresh worker in production
- Version your models — Cube models are code; store in Git, review changes, deploy via CI/CD