ClickHouse data source

Updated at:

The ClickHouse data source lets you read data from and write data to ClickHouse over a bidirectional channel. This topic describes ClickHouse data synchronization capabilities supported by DataWorks.

Supported versions

The following Alibaba Cloud ClickHouse versions are compatible with the listed JDBC driver versions:

JDBC driver version

Alibaba Cloud ClickHouse kernel version

0.2.4

20.8, 21.8

0.4.0, 0.4.2

22.8, 23.8, 25.3

Limits

The ClickHouse data source supports only batch reads and writes. Details:

  • You can use a Serverless resource group.

  • ClickHouse can be connected through JDBC, but data can be read only through JDBC Statement.

  • You can select some columns and reorder columns by specifying them.

  • To limit ClickHouse load, when ClickHouse Writer uses INSERT mode, we recommend limiting system throughput to at most 1,000 transactions per second (TPS).

  • Single-table batch synchronization with ClickHouse supports only Alibaba Cloud ClickHouse.

Supported field types

The following common Alibaba Cloud ClickHouse data types are supported. For the complete list of Alibaba Cloud ClickHouse types, see Data types. Other types in the open-source ClickHouse data type set are not supported. For the complete open-source list, see ClickHouse documentation.

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 has no separate Boolean type. Use UInt8 or Int8.

Supported

Array

Partially supported.

Supported when array elements are integers, floating-point numbers, strings, or DateTime64 values with millisecond precision.

Supported

Tuple

Supported

Supported

Domain(IPv4,IPv6)

Supported

Supported

Enum8

Supported

Supported

Enum16

Supported

Supported

Nullable

Supported

Supported

Nested

Partially supported.

Nested values are supported when their nested data types are integers, floating-point numbers, strings, or DateTime64 values with millisecond precision.

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 Data source configuration. You can view parameter descriptions in the DataWorks console to understand the meanings of the parameters when you add a data source.

Develop data synchronization tasks

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

Configure a single-table batch synchronization task

Configure a full-database batch read synchronization task

For the procedure, see Batch database synchronization configuration.

Appendix: Sample scripts 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 Script mode configuration. 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.

Reader sample script

{
    "type": "job",
    "version": "2.0",
    "steps": [
        {
            "stepType": "clickhouse", //Plug-in name.
            "parameter": {
                "fetchSize":1024,//Number of records fetched in each batch by the plug-in and database server.
                "datasource": "example",
                "column": [   //Column names.
                    "id",
                    "name"
                ],
                "where": "",    //Filter condition.
                "splitPk": "",  //Split key.
                "table": ""    //Table name.
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "clickhouse",
            "parameter": {
                "postSql": [
                    "update @table set db_modify_time = now() where db_id = 1"
                ],
                "datasource": "example",    //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"  //Maximum number of error records during synchronization.
        },
        "speed": {
         "throttle":true,//When throttle is false, mbps is ignored and throughput is unlimited; when true, throughput is limited.
            "concurrent":1 //Job concurrency.
            "mbps":"12",//Rate limit. Here, 1 mbps = 1 MB/s.
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Reader script parameters

Parameter

Description

Required

Default value

datasource

The data source name. In script mode, you can add a data source. The value must match the name of the added data source.

Yes

None

table

The table to synchronize, described in JSON.

Note

tableIt must be included in the connection configuration unit.

Yes

None

fetchSize

The number of records retrieved in each batch by the plug-in and database server. This controls the number of network interactions between Data Integration and the server and can improve data extraction performance.

Note

An excessively large fetchSize can cause an out-of-memory (OOM) error in the synchronization process. Increase it gradually based on ClickHouse load.

No

1,024

column

ClickHouse fields to read, separated by commas. Example: "column": ["id", "name", "age"].

Note

columnThe column setting is required and cannot be empty.

Yes

None

jdbcUrl

JDBC connection information for the source database. The jdbcUrl setting belongs in the connection configuration unit.

  • Only one value can be specified per database.

  • The jdbcUrl format follows the official ClickHouse format and can include additional connection parameters. Example:jdbc:clickhouse://localhost:3306/test?user=root&password=&useUnicode=true&characterEncoding=gbk &autoReconnect=true&failOverReadOnly=false.

Yes

None

username

Data source username.

Yes

None

password

Password for the specified data source user.

Yes

None

splitPk

When extracting data from ClickHouse, specifying splitPk means that you want to split the data by the field represented by splitPk. Synchronization then starts concurrent tasks to improve efficiency.

Note

When splitPk is configured, fetchSize is required.

No

None

where

A filter condition. In practice, you may synchronize the current day’s data. Set the where condition to gmt_create>$bizdate.

whereThis condition enables incremental synchronization. If the where statement is absent, either because the where key or value is missing, all data is synchronized.

No

None

Writer sample script

{
    "type":"job",
    "version":"2.0",//Version number.
    "steps":[
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"clickhouse",//Plug-in name.
            "parameter":{
                "username": "",
                "password": "",
                "column": [//Fields.
                    "id",
                    "name"
                ],
                "connection": [
                    {
                        "table": [//Table name.
                            "ClickHouse_table"
                        ],
                        "jdbcUrl": "jdbc:clickhouse://ip:port/database"
                    }
                ],
                "preSql": [ //SQL statements to run before the synchronization task.
                    "TRUNCATETABLEIFEXISTStablename"
                ],
                "postSql": [//SQL statements to run after the synchronization task.
                    "ALTERTABLEtablenameUPDATEcol1=1WHEREcol2=2"
                ],
                "batchSize": "1024",
                "batchByteSize": "67108864",
                "writeMode": "insert"
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//Number of error records.
        },
        "speed":{
            "throttle":true,//When throttle is false, mbps is ignored and throughput is unlimited; when true, throughput is limited.
            "concurrent":1, //Job concurrency.
            "mbps":"12"//Rate limit. Here, 1 mbps = 1 MB/s.
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Writer script parameters

Parameter

Description

Required

Default value

jdbcUrl

JDBC connection information for the destination database. jdbcUrl belongs in the connection configuration unit.

  • Only one value can be specified per database.

  • jdbcUrl follows the official ClickHouse format and can include additional connection parameters. Example:jdbc:clickhouse://127.0.0.1:3306/database.

Yes

None

username

Data source username.

Yes

None

password

Password for the specified data source user.

Yes

None

table

Name of the table to write, described as a JSON array.

Note

tableIt must be included in the connection configuration unit.

Yes

None

column

Destination table fields to write, separated by commas. Example: "column": ["id", "name", "age"].

Note

columnThe column setting is required and cannot be empty.

Yes

None

preSql

Standard SQL statements to run before writing data to the destination table.

No

None

postSql

Standard SQL statements to run after writing data to the destination table.

No

None

batchSize

Number of records submitted in one batch. This greatly reduces network interactions between the synchronization system and ClickHouse and improves throughput. An excessively large value can cause an out-of-memory (OOM) error in the synchronization process.

No

1,024