ClickHouse data source
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
For the procedure, see Codeless UI configuration and Script mode configuration.
For all script mode parameters and sample scripts, see Appendix: Sample scripts and parameters.
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: 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.
| 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 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.
| 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: 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 |