Skip to main content

The Clickhouse plugin for dbt (data build tool)

Project description

clickhouse dbt logo



This plugin ports dbt functionality to Clickhouse.

We do not test over older versions of Clickhouse. The plugin uses syntax that requires version 22.1 or newer.


Use your favorite Python package manager to install the app from PyPI, e.g.

pip install dbt-clickhouse

Supported features

  • Table materialization
  • View materialization
  • Incremental materialization
  • Seeds
  • Sources
  • Docs generate
  • Tests
  • Snapshots
  • Ephemeral materialization

Usage Notes


The dbt model database.schema.table is not compatible with Clickhouse because Clickhouse does not support a schema. So we use a simple model schema.table, where schema is the Clickhouse's database. Please, don't use default database!

Model Configuration

Option Description Required?
engine The table engine (type of table) to use when creating tables Optional (default: MergeTree())
order_by A tuple of column names or arbitrary expressions. This allows you to create a small sparse index that helps find data faster. Optional (default: tuple())
partition_by A partition is a logical combination of records in a table by a specified criterion. The partition key can be any expression from the table columns. Optional
unique_key A tuple of column names that uniquely identify rows. For more details on uniqueness constraints, see here. Optional
inserts_only This property is relevant only for incremental materialization. If set to True, incremental updates will be inserted directly to the target table without creating intermediate table. This option has the potential of significantly improve performance and avoid memory limitations on big updates. Optional
settings A dictionary with custom settings for INSERT INTO and CREATE AS SELECT queries. Optional

Example Profile

  target: dev
      type: clickhouse
      schema: [database name]

      # optional
      driver: [http] # http or native.  If not set will autodetermine base one port
      port: [port]  # default 8123
      user: [user] # default 'default'
      host: [] # default localhost
      password: [password] # default ''
      verify: [verify] # default True
      secure: [secure] # default False
      connect_timeout: [10] # default 10 seconds.
      custom_settings: {} # Custom seetings for the connection - default is empty.

Running Tests

This adapter passes all of dbt basic tests as presented in dbt's official docs:

Note: The only feature that is not supported and not tested is Ephemeral materialization.

Tests running command: pytest tests/integration

You can customize a few test params through environment variables. In order to provide custom params you'll need to create test.env file under root (remember not to commit this file!) and define the following env variables inside:

  1. HOST_ENV_VAR_NAME - Default=localhost
  2. USER_ENV_VAR_NAME - your ClickHouse username. Default=default
  3. PASSWORD_ENV_VAR_NAME - your ClickHouse password. Default=''
  4. PORT_ENV_VAR_NAME - ClickHouse client port. Default=8123
  5. RUN_DOCKER_ENV_VAR_NAME - Identify whether to run clickhouse-server docker image (see tests/docker-compose.yml). Default=False. Set it to True if you'd like to raise a docker image (assuming docker-compose is installed in your machine) during tests that launches a clickhouse-server. Note: If you decide to run a docker image you should set PORT_ENV_VAR_NAME to 10900 too.

Original Author

ClickHouse wants to thank @silentsokolov for creating this connector and for their valuable contributions.

Update 05/31/2022

  • Incremental changes of an incremental model are loaded into a MergeTree table instead of in-memory temporary table. This removed memory limitations - Clickhouse recommends that in-memory table engines should not exceed 100 million rows.
  • Incremental model supports 'inserts_only' mode where incremental changes are loaded directly to the target table instead of creating a temporary table for the changes and running another insert-into command. This mode is relevant only for immutable data, and can accelerate dramatically the performance of the incremental materialization.
  • Fix update and delete in snapshots.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dbt-clickhouse-1.1.5.tar.gz (23.4 kB view hashes)

Uploaded source

Built Distribution

dbt_clickhouse-1.1.5-py2.py3-none-any.whl (25.2 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page