{"id":25148,"library":"cubejs-schema-compiler","title":"Cube.js Schema Compiler","description":"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.","status":"active","version":"0.33.8","language":"javascript","source_language":"en","source_url":"https://github.com/cube-js/cube.js","tags":["javascript","typescript"],"install":[{"cmd":"npm install cubejs-schema-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add cubejs-schema-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add cubejs-schema-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Shared utilities and types used across Cube.js packages","package":"@cubejs-backend/shared","optional":false},{"reason":"Internal dependency for schema compilation (likely self-referencing)","package":"@cubejs-backend/schema-compiler","optional":true},{"reason":"Functional utilities used internally","package":"ramda","optional":false},{"reason":"Date manipulation for time dimension handling","package":"moment","optional":false}],"imports":[{"note":"Named export, not default. Available in both ESM and CJS.","wrong":"import SchemaCompiler from '@cubejs-backend/schema-compiler'","symbol":"SchemaCompiler","correct":"import { SchemaCompiler } from '@cubejs-backend/schema-compiler'"},{"note":"Name is CubeValidator, not SchemaValidator.","wrong":"import { SchemaValidator } from '@cubejs-backend/schema-compiler'","symbol":"CubeValidator","correct":"import { CubeValidator } from '@cubejs-backend/schema-compiler'"},{"note":"For building SQL queries from schema.","symbol":"QueryBuilder","correct":"import { QueryBuilder } from '@cubejs-backend/schema-compiler'"},{"note":"Maps cube data types to database-specific types.","symbol":"DataTypeMapper","correct":"import { DataTypeMapper } from '@cubejs-backend/schema-compiler'"},{"note":"Base class for measure definitions.","symbol":"BaseMeasure","correct":"import { BaseMeasure } from '@cubejs-backend/schema-compiler'"}],"quickstart":{"code":"import { SchemaCompiler } from '@cubejs-backend/schema-compiler';\n\nconst compiler = new SchemaCompiler({\n  dataSource: 'my_db',\n  schemaVersion: '1.0.0',\n  authInfo: {}, // optional auth\n});\n\nconst schema = {\n  cubes: [{\n    name: 'orders',\n    measures: [{\n      name: 'count',\n      type: 'count'\n    }],\n    dimensions: [{\n      name: 'status',\n      type: 'string',\n      sql: 'status'\n    }]\n  }]\n};\n\nconst compiled = compiler.compile(schema);\nconsole.log(compiled.sql); // outputs generated SQL","lang":"typescript","description":"Shows how to instantiate SchemaCompiler, define a cube schema, and compile it to an SQL query."},"warnings":[{"fix":"Upgrade to Node.js 12+ (prefer 14 or 16).","message":"Cube.js v0.33 requires Node.js >=12 (dropped Node 10 support).","severity":"breaking","affected_versions":">=0.33.0"},{"fix":"Use 'sql' alias or custom SQL expressions instead.","message":"The 'rename' option in cube schema definitions is deprecated and will be removed in v0.34.","severity":"deprecated","affected_versions":">=0.32.0"},{"fix":"Use `await compiler.compile(schema)` or handle promise.","message":"SchemaCompiler.compile() returns a promise, not synchronously. Forgetting to await leads to undefined SQL.","severity":"gotcha","affected_versions":">=0.30.0"},{"fix":"Set `\"esModuleInterop\": true` in tsconfig.json.","message":"When using TypeScript, ensure 'esModuleInterop' is true in tsconfig, otherwise imports from ramda/moment may break.","severity":"gotcha","affected_versions":">=0.33.0"},{"fix":"Pass `dataSource` in the constructor options.","message":"The method `SchemaCompiler.registerAdapter()` is deprecated; use constructor's `dataSource` option instead.","severity":"deprecated","affected_versions":">=0.31.0"},{"fix":"Export `module.exports = { cubes: [...] }`.","message":"Cube schema files must export a `schema` object, not a class. Common mistake: exporting a class instance.","severity":"gotcha","affected_versions":">=0.29.0"},{"fix":"Explicitly set `refreshKey` in pre-aggregations if old behavior needed.","message":"v0.30 changed pre-aggregation syntax: `refreshKey` now defaults to `every: '1 hour'` instead of `every: '1 minute'`.","severity":"breaking","affected_versions":">=0.30.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `const result = await compiler.compile(schema);`","cause":"SchemaCompiler.compile() called without awaiting, resulting in undefined promise.","error":"TypeError: Cannot read property 'map' of undefined"},{"fix":"Ensure the `dataSource` option matches a configured data source in Cube.js config.","cause":"Missing or misspelled data source name in constructor options.","error":"Error: Data source 'my_db' is not configured"},{"fix":"Use `module.exports = { cubes: [...] };` instead of `export default { cubes: [...] };`","cause":"Using ES module export syntax in a CommonJS schema file.","error":"SyntaxError: Unexpected token 'export'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}