# Repository: cube-js/cube # Stars: 19814 ## CLAUDE.md # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Repository Overview Cube is a semantic layer for building data applications. This is a monorepo containing the complete Cube ecosystem including: - Cube backend server and core components - Client libraries for JavaScript/React/Vue/Angular - Database drivers for various data sources - Documentation site - Rust components (CubeSQL, CubeStore) ## Development Commands **Note: This project uses Yarn as the package manager.** ### Core Build Commands ```bash # Build all packages yarn build # Run TypeScript compilation across all packages yarn tsc # Watch mode for TypeScript compilation yarn tsc:watch # Clean build artifacts yarn clean # Run linting across all packages yarn lint # Fix linting issues yarn lint:fix # Lint package.json files yarn lint:npm ``` ### Testing Commands ```bash # Run tests (most packages have individual test commands) yarn test # Test individual packages cd packages/cubejs-[package-name] yarn test ``` ### Documentation Development The documentation is in `/docs` directory: ```bash cd docs yarn dev # Start development server yarn build # Build for production ``` ## Architecture Overview ### Monorepo Structure - **`/packages`**: All JavaScript/TypeScript packages managed by Lerna - Core packages: `cubejs-server-core`, `cubejs-schema-compiler`, `cubejs-query-orchestrator` - Client libraries: `cubejs-client-core`, `cubejs-client-react`, etc. - Database drivers: `cubejs-postgres-driver`, `cubejs-bigquery-driver`, etc. - API layer: `cubejs-api-gateway` - **`/rust`**: Rust components including CubeSQL (SQL interface) and CubeStore (distributed storage) - **`/docs`**: Next.js documentation site - **`/examples`**: Example implementations and recipes ### Key Components 1. **Schema Compiler**: Compiles data models into executable queries 2. **Query Orchestrator**: Manages query execution, caching, and pre-aggregations 3. **API Gateway**: Provides REST, GraphQL, and SQL APIs 4. **CubeSQL**: Postgres-compatible SQL interface (Rust) 5. **CubeStore**: Distributed OLAP storage engine (Rust) 6. **Tesseract**: Native SQL planner (Rust) located in `/rust/cubesqlplanner` - enabled via `CUBESQL_SQL_PUSH_DOWN=true` environment variable ### Package Management - Uses Yarn workspaces with Lerna for package management - TypeScript compilation is coordinated across packages - Jest for unit testing with package-specific configurations ## Testing Approach ### Unit Tests - Most packages have Jest-based unit tests in `/test` directories - TypeScript packages use `jest.config.js` with TypeScript compilation - Snapshot testing for SQL compilation and query planning ### Integration Tests - Driver-specific integration tests in `/packages/cubejs-testing-drivers` - End-to-end tests in `/packages/cubejs-testing` - Docker-based testing environments for database drivers ### Test Commands ```bash # Individual package testing cd packages/[package-name] yarn test # Driver integration tests (requires Docker) cd packages/cubejs-testing-drivers yarn test ``` ## Development Workflow 1. **Making Changes**: Work in individual packages, changes are coordinated via Lerna 2. **Building**: Use `yarn tsc` to compile TypeScript across all packages 3. **Testing**: Run relevant tests for modified packages 4. **Linting**: Ensure code passes `yarn lint` before committing ## Git Use conventional commits with these prefixes: - `feat:` — new features - `fix:` — bug fixes - `docs:` — documentation changes - `refactor:` — code refactoring Include scope in parentheses when applicable, e.g., `fix(tesseract):` or `feat(databricks-jdbc-driver):`. ## Common File Patterns - `*.test.ts/js`: Jest unit tests - `jest.config.js`: Jest configuration per package - `tsconfig.json`: TypeScript configuration (inherits from root) - `CHANGELOG.md`: Per-package changelogs maintained by Lerna - `src/`: Source code directory - `dist/`: Compiled output (not committed) ## Important Notes - This is documentation for the old Cube docs site structure (the existing `/docs/CLAUDE.md` refers to the documentation site) - The main Cube application development happens in `/packages` - For data model changes, focus on `cubejs-schema-compiler` package - For query execution changes, focus on `cubejs-query-orchestrator` package - Database connectivity is handled by individual driver packages ## Key Dependencies - **Lerna**: Monorepo management and publishing - **TypeScript**: Primary language for most packages - **Jest**: Testing framework - **Rollup**: Bundling for client libraries - **Docker**: Testing environments for database drivers ## README.md ![]()

Cube Core — Open-Source Semantic Layer


[Website](https://cube.dev?ref=github-readme) • [Docs](https://cube.dev/docs?ref=github-readme) • [Examples](https://cube.dev/docs/examples?ref=github-readme) • [Blog](https://cube.dev/blog?ref=github-readme) • [Slack](https://slack.cube.dev?ref=github-readme) • [X](https://twitter.com/the_cube_dev) [![npm version](https://badge.fury.io/js/%40cubejs-backend%2Fserver.svg)](https://badge.fury.io/js/%40cubejs-backend%2Fserver) [![GitHub Actions](https://github.com/cube-js/cube/workflows/Build/badge.svg)](https://github.com/cube-js/cube/actions?query=workflow%3ABuild+branch%3Amaster) [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fcube-js%2Fcube.js.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fcube-js%2Fcube.js?ref=badge_shield) __Cube Core is an open-source semantic layer.__ Cube Core can be used to build embedded analytics in your applications, create your own business intelligence tool or provide context about data to AI agents. Cube Core is headless and comes with multiple APIs for embedded analytics and BI: REST, GraphQL, and SQL. If you are looking for a fully integrated platform, check out [Cube](https://cube.dev), a modern AI-first business intelligence platform. We use Cube Core to power it.

Learn more about connecting Cube to data sources and analytics & visualization tools.

Cube Core was designed to work with all SQL data sources, including cloud data warehouses like Snowflake, Databricks, and BigQuery; query engines like Presto and Amazon Athena; and application databases like Postgres. Cube Core has a built-in relational caching engine to provide sub-second latency and high concurrency for API requests. ## Why Cube Core? Every business intelligence tool relies on a semantic layer as its core engine—a critical component that defines metrics, dimensions, and business logic while abstracting the complexity of underlying data sources. However, most semantic layers are proprietary, tightly coupled to specific BI platforms, and cannot be reused across different applications. Cube Core is an open-source project that aims to create an open, modern semantic layer that can be used to power any analytics applications and AI agents. By decoupling the semantic layer from specific tools and making it accessible through standard APIs, Cube Core enables organizations to define their metrics once and use them everywhere—from BI tools to embedded analytics to AI agents. ## Getting Started 🚀 You can get started with Cube locally or self-host it with [Docker](https://www.docker.com/). Once Docker is installed, in a new folder for your project, run the following command: ```bash docker run -p 4000:4000 \ -p 15432:15432 \ -v ${PWD}:/cube/conf \ -e CUBEJS_DEV_MODE=true \ cubejs/cube ``` Then, open http://localhost:4000 in your browser to continue setup. For a step-by-step guide, [see the docs](https://cube.dev/cube-core/getting-started/create-a-project?ref=github-readme). ### Cube — Complete Modern BI Tool from Cube Core Creators [Cube](https://cube.dev?ref=github-readme) is a complete modern agentic analytics platform built on Cube Core. It provides a fully integrated solution with a user-friendly interface, advanced analytics capabilities, and managed infrastructure. Get started now ## Resources - [Documentation](https://cube.dev/docs?ref=github-readme) - [Getting Started](https://cube.dev/cube-core/getting-started?ref=github-readme) - [Examples & Tutorials](https://cube.dev/recipes?ref=github-readme) - [Architecture](https://cube.dev/docs/introduction) ## Contributing There are many ways you can contribute to Cube Core! Here are a few possibilities: * Star this repo and follow us on [X](https://twitter.com/the_cube_dev). * Add Cube to your stack on [Stackshare](https://stackshare.io/cube-js). * Upvote issues with 👍 reaction so we know what the demand is for particular issues to prioritize them within the roadmap. * Create issues every time you feel something is missing or goes wrong. * Ask questions on [Stack Overflow with cube.js tag](https://stackoverflow.com/questions/tagged/cube.js) if others might have these questions as well. * Provide pull requests for all open issues and especially for those with [help wanted](https://github.com/cube-js/cube/issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted") and [good first issue](https://github.com/cube-js/cube/issues?q=is%3Aissue+is%3Aopen+label%3A"good+first+issue") labels. All sorts of contributions are **welcome and extremely helpful** 🙌 Please refer to [the contribution guide](https://github.com/cube-js/cube/blob/master/CONTRIBUTING.md) for more information. ## License Cube Client is [MIT licensed](./packages/cubejs-client-core/LICENSE). Cube Backend is [Apache 2.0 licensed](./packages/cubejs-server/LICENSE). [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fcube-js%2Fcube.js.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fcube-js%2Fcube.js?ref=badge_large)