All Products
Search
Document Center

DataWorks:ClickHouse data source

Last Updated:Apr 25, 2025

DataWorks provides ClickHouse Reader and ClickHouse Writer for you to read data from and write data to ClickHouse data sources. This topic describes the capabilities of synchronizing data from or to ClickHouse data sources.

Supported ClickHouse versions

The following table describes the supported ClickHouse versions and the Java Database Connectivity (JDBC) driver versions that are compatible with the ClickHouse versions.

JDBC driver version

Version of ApsaraDB for ClickHouse data source

V0.2.4

V20.8 and V21.8

V0.4.0

V22.8 and V23.8

Limits

ClickHouse data sources support only batch data read and write. Take note of the following items:

  • ClickHouse data sources support serverless resource groups and exclusive resource groups for Data Integration.

  • ClickHouse Reader and ClickHouse Writer connect to ClickHouse databases by using Java Database Connectivity (JDBC) and can read data from and write data to the databases only by using JDBC statements.

  • ClickHouse Reader allows you to read data from the specified columns in an order different from that specified in the schema of the source table. ClickHouse Writer allows you to write data to the specified columns in an order different from that specified in the schema of the destination table.

  • If ClickHouse Writer writes data in INSERT mode, we recommend that you throttle the transactions per second (TPS) to 1,000 to prevent high workloads on ClickHouse.

Supported data types

The following table lists the ApsaraDB for ClickHouse data types supported by ClickHouse Reader and ClickHouse Writer. For information about all ApsaraDB for ClickHouse data types, see Data types. Open source ClickHouse data types except those in the following table are not supported. For information about open source ClickHouse data types, see ClickHouse Docs.

Data type

ClickHouse Reader

ClickHouse Writer

Int8

Supported

Supported

Int16

Supported

Supported

Int32

Supported

Supported

Int64

Supported

Supported

UInt8

Supported

Supported

UInt16

Supported

Supported

UInt32

Supported

Supported

UInt64

Supported

Supported

Float32

Supported

Supported

Float64

Supported

Supported

Decimal

Supported

Supported

String

Supported

Supported

FixedString

Supported

Supported

Date

Supported

Supported

DateTime

Supported

Supported

DateTime64

Supported

Supported

Boolean

Supported

Note

ClickHouse does not have a separate Boolean type. You can use UInt8 and Int8.

Supported

Array

Partially supported.

This data type is supported only if the elements in an array are of one of the following types: integer, floating point, string, or DateTime64 (accurate to milliseconds).

Supported

Tuple

Supported

Supported

Domain(IPv4,IPv6)

Supported

Supported

Enum8

Supported

Supported

Enum16

Supported

Supported

Nullable

Supported

Supported

Nested

Partially supported.

This data type is supported only if the nested fields are of one of the following types: integer, floating point, string, or DateTime64 (accurate to milliseconds).

Supported

Add a data source

Before you develop a synchronization task in DataWorks, you must add the required data source to DataWorks by following the instructions in Add and manage data sources. You can view the infotips of parameters in the DataWorks console to understand the meanings of the parameters when you add a data source.

Develop a data synchronization task

For information about the entry point for and the procedure of configuring a synchronization task, see the following configuration guides.

Configure a batch synchronization task to synchronize data of a single table

Configure synchronization settings to implement batch synchronization of all data in a database

For more information about the configuration procedure, see Configure a synchronization task in Data Integration.

Appendix: Code and parameters

Configure a batch synchronization task by using the code editor

If you want to configure a batch synchronization task by using the code editor, you must configure the related parameters in the script based on the unified script format requirements. For more information, see Configure a batch synchronization task by using the code editor. The following information describes the parameters that you must configure for data sources when you configure a batch synchronization task by using the code editor.

Code for ClickHouse Reader

{
    "type": "job",
    "version": "2.0",
    "steps": [
        {
            "stepType": "clickhouse", // The plug-in name. 
            "parameter": {
                "fetchSize":1024,// The number of data records to read at a time. 
                "datasource": "example",
                "column": [   // The names of the columns. 
                    "id",
                    "name"
                ],
                "where": "",    // The WHERE clause. 
                "splitPk": "",  // The shard key. 
                "table": ""    // The name of the table. 
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "clickhouse",
            "parameter": {
                "postSql": [
                    "update @table set db_modify_time = now() where db_id = 1"
                ],
                "datasource": "example",    // The name of the data source. 
                "batchByteSize": "67108864",
                "column": [
                    "id",
                    "name"
                ],
                "writeMode": "insert",
                "encoding": "UTF-8",
                "batchSize": 1024,
                "table": "ClickHouse_table",
                "preSql": [
                    "delete from @table where db_id = -1"
                ]
            },
            "name": "Writer",
            "category": "writer"
        }
    ],
    "setting": {
        "executeMode": null,
        "errorLimit": {
            "record": "0"  // The maximum number of dirty data records allowed. 
        },
        "speed": {
         "throttle":true,// Specifies whether to enable throttling. The value false indicates that throttling is disabled, and the value true indicates that throttling is enabled. The mbps parameter takes effect only when the throttle parameter is set to true. 
            "concurrent":1 // The maximum number of parallel threads. 
            "mbps":"12",// The maximum transmission rate. Unit: MB/s. 
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Parameters in code for ClickHouse Reader

Parameter

Description

Required

Default value

datasource

The name of the data source. It must be the same as the name of the added data source. You can add data sources by using the code editor.

Yes

No default value

table

The name of the table from which you want to read data. Specify the name in the JSON format.

Note

The table parameter must be included in the connection parameter.

Yes

No default value

fetchSize

The number of data records to read at a time. This parameter determines the number of interactions between Data Integration and the source database and affects read efficiency.

Note

If you set this parameter to an excessively large value, an out of memory (OOM) error may occur during data synchronization. You can increase the value of this parameter based on the workloads on ClickHouse.

No

1,024

column

The names of the columns from which you want to read data. Separate the names with commas (,). Example: "column": ["id", "name", "age"].

Note

You must specify the column parameter.

Yes

No default value

jdbcUrl

The JDBC URL of the source database. The jdbcUrl parameter must be included in the connection parameter.

  • You can configure only one JDBC URL for a database.

  • The value format of the jdbcUrl parameter must be in accordance with the official specifications of ClickHouse. You can also specify additional JDBC connection properties in the value of this parameter. Example: jdbc:clickhouse://localhost:3306/test?user=root&password=&useUnicode=true&characterEncoding=gbk &autoReconnect=true&failOverReadOnly=false.

Yes

No default value

username

The username that you can use to connect to the database.

Yes

No default value

password

The password that you can use to connect to the database.

Yes

No default value

splitPk

The field that is used for data sharding when ClickHouse Reader reads data. If you specify this parameter, the source table is sharded based on the value of this parameter. Data Integration then runs parallel threads to read data. This way, data can be synchronized more efficiently.

Note

If you specify the splitPk parameter, you must specify the fetchSize parameter.

No

No default value

where

The WHERE clause. For example, you can set this parameter to gmt_create > $bizdate to read the data that is generated on the current day.

You can use the WHERE clause to read incremental data. If the where parameter is not provided or is left empty, ClickHouse Reader reads all data.

No

No default value

Code for ClickHouse Writer

{
    "type":"job",
    "version":"2.0",// The version number. 
    "steps":[
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"clickhouse",// The plug-in name. 
            "parameter":{
                "username": "",
                "password": "",
                "column": [// The names of the columns. 
                    "id",
                    "name"
                ],
                "connection": [
                    {
                        "table": [// The name of the table. 
                            "ClickHouse_table"
                        ],
                        "jdbcUrl": "jdbc:clickhouse://ip:port/database"
                    }
                ],
                "preSql": [ // The SQL statement that you want to execute before the synchronization task is run. 
                    "TRUNCATETABLEIFEXISTStablename"
                ],
                "postSql": [// The SQL statement that you want to execute after the synchronization task is run. 
                    "ALTERTABLEtablenameUPDATEcol1=1WHEREcol2=2"
                ],
                "batchSize": "1024",
                "batchByteSize": "67108864",
                "writeMode": "insert"
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"// The maximum number of dirty data records allowed. 
        },
        "speed":{
            "throttle":true,// Specifies whether to enable throttling. The value false indicates that throttling is disabled, and the value true indicates that throttling is enabled. The mbps parameter takes effect only when the throttle parameter is set to true. 
            "concurrent":1, // The maximum number of parallel threads. 
            "mbps":"12",// The maximum transmission rate. Unit: MB/s. 
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Parameters in code for ClickHouse Writer

Parameter

Description

Required

Default value

jdbcUrl

The JDBC URL of the destination database. The jdbcUrl parameter must be included in the connection parameter.

  • You can configure only one JDBC URL for a database.

  • The value format of the jdbcUrl parameter must be in accordance with the official specifications of ClickHouse. You can also specify additional JDBC connection properties in the value of this parameter. Example: jdbc:clickhouse://127.0.0.1:3306/database.

Yes

No default value

username

The username that you can use to connect to the database.

Yes

No default value

password

The password that you can use to connect to the database.

Yes

No default value

table

The name of the table to which you want to write data. Specify the name in a JSON array.

Note

The table parameter must be included in the connection parameter.

Yes

No default value

column

The names of the columns to which you want to write data. Separate the names with commas (,). Example: "column": ["id", "name", "age"].

Note

You must specify the column parameter.

Yes

No default value

preSql

The SQL statement that you want to execute before the synchronization task is run.

No

No default value

postSql

The SQL statement that you want to execute after the synchronization task is run.

No

No default value

batchSize

The number of data records to write at a time. Set this parameter to an appropriate value based on your business requirements. This greatly reduces the interactions between Data Integration and ClickHouse and increases throughput. If you set this parameter to an excessively large value, an OOM error may occur during data synchronization.

No

1,024