Cube.js Schema Compiler

0.33.8 verified Fri May 01 auth: no javascript

Core schema compiler for Cube.js (v0.33.8), the analytics API platform. This package transforms Cube.js data schema definitions (data model files) into executable SQL queries. It compiles SQL for various databases (Postgres, BigQuery, MySQL, etc.) and supports pre-aggregations, joins, dimensions, measures, and time granularities. Weekly releases under the Cube.js monorepo. Key differentiator: provides an ORM-like layer for analytics SQL generation, enabling complex analytical queries (funnels, retention) without writing raw SQL. Fully typed with TypeScript. Requires Cube.js backend server for execution.

Common errors

error TypeError: Cannot read property 'map' of undefined ↓

cause SchemaCompiler.compile() called without awaiting, resulting in undefined promise.

fix

Use const result = await compiler.compile(schema);

error Error: Data source 'my_db' is not configured ↓

cause Missing or misspelled data source name in constructor options.

fix

Ensure the dataSource option matches a configured data source in Cube.js config.

error SyntaxError: Unexpected token 'export' ↓

cause Using ES module export syntax in a CommonJS schema file.

fix

Use module.exports = { cubes: [...] }; instead of export default { cubes: [...] };

Warnings

breaking Cube.js v0.33 requires Node.js >=12 (dropped Node 10 support). ↓

fix Upgrade to Node.js 12+ (prefer 14 or 16).

deprecated The 'rename' option in cube schema definitions is deprecated and will be removed in v0.34. ↓

fix Use 'sql' alias or custom SQL expressions instead.

gotcha SchemaCompiler.compile() returns a promise, not synchronously. Forgetting to await leads to undefined SQL. ↓

fix Use `await compiler.compile(schema)` or handle promise.

gotcha When using TypeScript, ensure 'esModuleInterop' is true in tsconfig, otherwise imports from ramda/moment may break. ↓

fix Set `"esModuleInterop": true` in tsconfig.json.

deprecated The method `SchemaCompiler.registerAdapter()` is deprecated; use constructor's `dataSource` option instead. ↓

fix Pass `dataSource` in the constructor options.

gotcha Cube schema files must export a `schema` object, not a class. Common mistake: exporting a class instance. ↓

fix Export `module.exports = { cubes: [...] }`.

breaking v0.30 changed pre-aggregation syntax: `refreshKey` now defaults to `every: '1 hour'` instead of `every: '1 minute'`. ↓

fix Explicitly set `refreshKey` in pre-aggregations if old behavior needed.

Install

npm install cubejs-schema-compiler

yarn add cubejs-schema-compiler

pnpm add cubejs-schema-compiler

Imports

SchemaCompiler

wrong

import SchemaCompiler from '@cubejs-backend/schema-compiler'

correct

import { SchemaCompiler } from '@cubejs-backend/schema-compiler'

Named export, not default. Available in both ESM and CJS.

CubeValidator

wrong

import { SchemaValidator } from '@cubejs-backend/schema-compiler'

correct

import { CubeValidator } from '@cubejs-backend/schema-compiler'

Name is CubeValidator, not SchemaValidator.

QueryBuilder

import { QueryBuilder } from '@cubejs-backend/schema-compiler'

For building SQL queries from schema.

DataTypeMapper

import { DataTypeMapper } from '@cubejs-backend/schema-compiler'

Maps cube data types to database-specific types.

BaseMeasure

import { BaseMeasure } from '@cubejs-backend/schema-compiler'

Base class for measure definitions.

Quickstart

Shows how to instantiate SchemaCompiler, define a cube schema, and compile it to an SQL query.

import { SchemaCompiler } from '@cubejs-backend/schema-compiler';

const compiler = new SchemaCompiler({
  dataSource: 'my_db',
  schemaVersion: '1.0.0',
  authInfo: {}, // optional auth
});

const schema = {
  cubes: [{
    name: 'orders',
    measures: [{
      name: 'count',
      type: 'count'
    }],
    dimensions: [{
      name: 'status',
      type: 'string',
      sql: 'status'
    }]
  }]
};

const compiled = compiler.compile(schema);
console.log(compiled.sql); // outputs generated SQL