Skip to main content

​
ClickHouse

ClickHouse is a fast and resource efficient open-source database for real-time applications and analytics.

​
Prerequisites

​
Setup

​
Manual

Add the following to a .env file in your Cube project: 
CUBEJS_DB_TYPE=clickhouse
CUBEJS_DB_HOST=my.clickhouse.host
CUBEJS_DB_NAME=my_clickhouse_database
CUBEJS_DB_USER=clickhouse_user
CUBEJS_DB_PASS=**********

​
Environment Variables

Environment VariableDescriptionPossible ValuesRequired
CUBEJS_DB_HOSTThe host URL for a databaseA valid database host URL✅
CUBEJS_DB_PORTThe port for the database connectionA valid port number❌
CUBEJS_DB_NAMEThe name of the database to connect toA valid database name✅
CUBEJS_DB_USERThe username used to connect to the databaseA valid database username✅
CUBEJS_DB_PASSThe password used to connect to the databaseA valid database password✅
CUBEJS_DB_CLICKHOUSE_READONLYWhether the ClickHouse user has read-only access or nottrue, false❌
CUBEJS_DB_CLICKHOUSE_COMPRESSIONWhether the ClickHouse client has compression enabled or nottrue, false❌
CUBEJS_DB_MAX_POOLThe maximum number of concurrent database connections to pool. Default is 20A valid number❌
CUBEJS_CONCURRENCYThe number of concurrent queries to the data sourceA valid number❌

​
Pre-Aggregation Feature Support

When using pre-aggregations with ClickHouse, you have to define indexes in pre-aggregations. Otherwise, you might get the following error: ClickHouse doesn't support pre-aggregations without indexes.

​
count_distinct_approx

Measures of type count_distinct_approx can not be used in pre-aggregations when using ClickHouse as a source database.

​
rollup_join

You can use rollup_join pre-aggregations to join data from ClickHouse and other data sources inside Cube Store. Alternatively, you can leverage ClickHouse support for integration table engines to join data from ClickHouse and other data sources inside ClickHouse. To do so, define table engines in ClickHouse and connect your ClickHouse as the only data source to Cube.

​
Pre-Aggregation Build Strategies

To learn more about pre-aggregation build strategies, head here.
FeatureWorks with read-only mode?Is default?
Batching✅✅
Export Bucket✅-
By default, ClickHouse uses batching to build pre-aggregations.

​
Batching

No extra configuration is required to configure batching for ClickHouse.

​
Export Bucket

Clickhouse driver only supports using AWS S3 for export buckets.

​
AWS S3

For improved pre-aggregation performance with large datasets, enable export bucket functionality by configuring Cube with the following environment variables:
Ensure the AWS credentials are correctly configured in IAM to allow reads and writes to the export bucket in S3.
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>

​
SSL

To enable SSL-encrypted connections between Cube and ClickHouse, set the CUBEJS_DB_SSL environment variable to true. For more information on how to configure custom certificates, please check out Enable SSL Connections to the Database.

​
Additional Configuration

You can connect to a ClickHouse database when your user’s permissions are restricted to read-only, by setting CUBEJS_DB_CLICKHOUSE_READONLY to true. You can connect to a ClickHouse database with compression enabled, by setting CUBEJS_DB_CLICKHOUSE_COMPRESSION to true.