|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Package Overview |
| 6 | + |
| 7 | +The Query Orchestrator is a multi-stage querying engine that manages query execution, caching, and pre-aggregations in Cube. It receives pre-aggregation SQL queries and executes them in exact order, ensuring up-to-date data structure and freshness. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +**Note: This project uses Yarn as the package manager.** |
| 12 | + |
| 13 | +```bash |
| 14 | +# Build the package |
| 15 | +yarn build |
| 16 | + |
| 17 | +# Build with TypeScript compilation |
| 18 | +yarn tsc |
| 19 | + |
| 20 | +# Watch mode for development |
| 21 | +yarn watch |
| 22 | + |
| 23 | +# Run all tests (unit + integration) |
| 24 | +yarn test |
| 25 | + |
| 26 | +# Run only unit tests |
| 27 | +yarn unit |
| 28 | + |
| 29 | +# Run only integration tests |
| 30 | +yarn integration |
| 31 | + |
| 32 | +# Run CubeStore integration tests specifically |
| 33 | +yarn integration:cubestore |
| 34 | + |
| 35 | +# Run linting |
| 36 | +yarn lint |
| 37 | + |
| 38 | +# Fix linting issues |
| 39 | +yarn lint:fix |
| 40 | +``` |
| 41 | + |
| 42 | +## Architecture Overview |
| 43 | + |
| 44 | +### Core Components |
| 45 | + |
| 46 | +The Query Orchestrator consists of several interconnected components: |
| 47 | + |
| 48 | +1. **QueryOrchestrator** (`src/orchestrator/QueryOrchestrator.ts`): Main orchestration class that coordinates query execution and manages drivers |
| 49 | +2. **QueryCache** (`src/orchestrator/QueryCache.ts`): Handles query result caching with configurable cache drivers |
| 50 | +3. **QueryQueue** (`src/orchestrator/QueryQueue.js`): Manages query queuing and background processing |
| 51 | +4. **PreAggregations** (`src/orchestrator/PreAggregations.ts`): Manages pre-aggregation building and loading |
| 52 | +5. **DriverFactory** (`src/orchestrator/DriverFactory.ts`): Creates and manages database driver instances |
| 53 | + |
| 54 | +### Cache and Queue Driver Architecture |
| 55 | + |
| 56 | +The orchestrator supports multiple backend drivers: |
| 57 | +- **Memory**: In-memory caching and queuing (development) |
| 58 | +- **CubeStore**: Distributed storage engine (production) |
| 59 | +- **Redis**: External Redis-based caching (legacy, being phased out) |
| 60 | + |
| 61 | +Driver selection logic in `QueryOrchestrator.ts:detectQueueAndCacheDriver()`: |
| 62 | +- Explicit configuration via `cacheAndQueueDriver` option |
| 63 | +- Environment variables (`CUBEJS_CACHE_AND_QUEUE_DRIVER`) |
| 64 | +- Auto-detection: Redis if `CUBEJS_REDIS_URL` exists, CubeStore for production, Memory for development |
| 65 | + |
| 66 | +### Query Processing Flow |
| 67 | + |
| 68 | +1. **Query Submission**: Queries enter through QueryOrchestrator |
| 69 | +2. **Cache Check**: QueryCache checks for existing results |
| 70 | +3. **Queue Management**: QueryQueue handles background execution |
| 71 | +4. **Pre-aggregation Processing**: PreAggregations component manages rollup tables |
| 72 | +5. **Result Caching**: Results stored via cache driver for future requests |
| 73 | + |
| 74 | +### Pre-aggregation System |
| 75 | + |
| 76 | +The pre-aggregation system includes: |
| 77 | +- **PreAggregationLoader**: Loads pre-aggregation definitions |
| 78 | +- **PreAggregationPartitionRangeLoader**: Handles partition range loading |
| 79 | +- **PreAggregationLoadCache**: Manages loading cache for pre-aggregations |
| 80 | + |
| 81 | +## Testing Structure |
| 82 | + |
| 83 | +### Unit Tests (`test/unit/`) |
| 84 | +- `QueryCache.test.ts`: Query caching functionality |
| 85 | +- `QueryQueue.test.ts`: Queue management and processing |
| 86 | +- `QueryOrchestrator.test.js`: Main orchestrator logic |
| 87 | +- `PreAggregations.test.js`: Pre-aggregation management |
| 88 | + |
| 89 | +### Integration Tests (`test/integration/`) |
| 90 | +- `cubestore/`: CubeStore-specific integration tests |
| 91 | +- Tests real database interactions and queue processing |
| 92 | + |
| 93 | +### Test Abstractions |
| 94 | +- `QueryCache.abstract.ts`: Shared test suite for cache implementations |
| 95 | +- `QueryQueue.abstract.ts`: Shared test suite for queue implementations |
| 96 | + |
| 97 | +## Key Design Patterns |
| 98 | + |
| 99 | +### Queue Processing Architecture |
| 100 | +The DEVELOPMENT.md file contains detailed sequence diagrams showing: |
| 101 | +- Queue interaction with CubeStore via specific queue commands (`QUEUE ADD`, `QUEUE RETRIEVE`, etc.) |
| 102 | +- Background query processing with heartbeat management |
| 103 | +- Result handling and cleanup |
| 104 | + |
| 105 | +### Driver Factory Pattern |
| 106 | +- `DriverFactory` type enables pluggable database drivers |
| 107 | +- `DriverFactoryByDataSource` supports multi-tenant scenarios |
| 108 | +- Separation between external (user data) and internal (cache/queue) drivers |
| 109 | + |
| 110 | +### Error Handling |
| 111 | +- `ContinueWaitError`: Signals when queries should continue waiting |
| 112 | +- `TimeoutError`: Handles query timeout scenarios |
| 113 | +- Proper cleanup and resource management across all components |
| 114 | + |
| 115 | +## Configuration |
| 116 | + |
| 117 | +Key configuration options in `QueryOrchestratorOptions`: |
| 118 | +- `externalDriverFactory`: Database driver for user data |
| 119 | +- `cacheAndQueueDriver`: Backend for caching and queuing |
| 120 | +- `queryCacheOptions`: Cache-specific settings |
| 121 | +- `preAggregationsOptions`: Pre-aggregation configuration |
| 122 | +- `rollupOnlyMode`: When enabled, only serves pre-aggregated data |
| 123 | +- `continueWaitTimeout`: Timeout for waiting operations |
| 124 | + |
| 125 | +## Development Notes |
| 126 | + |
| 127 | +- Uses TypeScript with relaxed strict settings (`tsconfig.json`) |
| 128 | +- Inherits linting rules from `@cubejs-backend/linter` |
| 129 | +- Jest configuration extends base repository config |
| 130 | +- Docker Compose setup for integration testing |
| 131 | +- Coverage reports generated in `coverage/` directory |
0 commit comments