A fonte de dados ClickHouse oferece canais bidirecionais de leitura e escrita para o ClickHouse. Este tópico descreve os recursos de sincronização de dados do ClickHouse compatíveis com o DataWorks.
Versões compatíveis
As versões do ApsaraDB for ClickHouse compatíveis e seus drivers JDBC correspondentes são:
|
Versão do driver JDBC |
Versão do kernel do ApsaraDB for ClickHouse |
|
0.2.4 |
20.8, 21.8 |
|
0.4.0, 0.4.2 |
22.8, 23.8, 25.3 |
Limitações
A fonte de dados ClickHouse oferece suporte apenas a leitura e escrita em lote, conforme detalhado abaixo.
Compatível com grupos de recursos serverless.
Permite conexões JDBC com o ClickHouse, mas a leitura de dados ocorre exclusivamente via JDBC Statement.
Oferece suporte a filtragem e reordenação de colunas. Especifique as colunas conforme necessário.
Para evitar sobrecarga no ClickHouse, limite o throughput do sistema (TPS) a no máximo 1.000 quando o ClickHouse Writer operar no modo INSERT.
A sincronização em lote de tabela única do ClickHouse é compatível apenas com o ApsaraDB for ClickHouse.
Tipos de coluna compatíveis
Os tipos de dados comuns do ApsaraDB for ClickHouse listados abaixo são compatíveis. Para consultar a lista completa de tipos de dados do ApsaraDB for ClickHouse, visualize Tipos de dados. Outros tipos presentes no conjunto oficial de tipos de dados do ClickHouse open source não são suportados. Para a lista completa de tipos de dados do ClickHouse open source, consulte a Documentação do ClickHouse.
|
Tipo de dado |
ClickHouse Reader |
ClickHouse Writer |
|
Int8 |
Suportado |
Suportado |
|
Int16 |
Suportado |
Suportado |
|
Int32 |
Suportado |
Suportado |
|
Int64 |
Suportado |
Suportado |
|
UInt8 |
Suportado |
Suportado |
|
UInt16 |
Suportado |
Suportado |
|
UInt32 |
Suportado |
Suportado |
|
UInt64 |
Suportado |
Suportado |
|
Float32 |
Suportado |
Suportado |
|
Float64 |
Suportado |
Suportado |
|
Decimal |
Suportado |
Suportado |
|
String |
Suportado |
Suportado |
|
FixedString |
Suportado |
Suportado |
|
Date |
Suportado |
Suportado |
|
DateTime |
Suportado |
Suportado |
|
DateTime64 |
Suportado |
Suportado |
|
Boolean |
Suportado Nota
O ClickHouse não possui um tipo Boolean específico. Utilize UInt8 ou Int8 como alternativa. |
Suportado |
|
Array |
Parcialmente suportado. Há suporte quando o tipo do elemento do array é inteiro, float, string ou DateTime64 com precisão de milissegundos. |
Suportado |
|
Tuple |
Suportado |
Suportado |
|
Domain(IPv4,IPv6) |
Suportado |
Suportado |
|
Enum8 |
Suportado |
Suportado |
|
Enum16 |
Suportado |
Suportado |
|
Nullable |
Suportado |
Suportado |
|
Nested |
Parcialmente suportado. Os tipos de elementos aninhados aceitam inteiros, floats, strings e DateTime64 com precisão de milissegundos. |
Suportado |
Adicionar uma fonte de dados
Antes de desenvolver uma tarefa de sincronização no DataWorks, adicione a fonte de dados necessária seguindo as instruções em Gerenciamento de fontes de dados. Consulte as descrições dos parâmetros no console do DataWorks para compreender o significado de cada parâmetro ao adicionar uma fonte de dados.
Desenvolver uma tarefa de sincronização de dados
Para obter informações sobre o ponto de entrada e o procedimento de configuração de uma tarefa de sincronização, consulte os guias de configuração a seguir.
Guia de configuração para tarefas de sincronização em lote de tabela única
Para o procedimento, visualize Configuração por UI sem código e Configuração em modo script.
Para o conjunto completo de parâmetros do modo script e uma demonstração de script, consulte o Apêndice: Demonstração de script e descrições de parâmetros abaixo.
Guia de configuração para sincronização de leitura em lote de banco de dados completo
Para o procedimento, visualize Configuração de sincronização de banco de dados em lote.
Apêndice: Demonstração de script e descrições de parâmetros
Configure uma tarefa de sincronização em lote usando o editor de código
Para configurar uma tarefa de sincronização em lote com o editor de código, defina os parâmetros relevantes no script respeitando os requisitos unificados de formato. Para mais detalhes, visualize Configuração em modo script. As informações a seguir descrevem os parâmetros obrigatórios para fontes de dados na configuração de tarefas de sincronização em lote via editor de código.
Exemplo de script do Reader
{
"type": "job",
"version": "2.0",
"steps": [
{
"stepType": "clickhouse", //Plugin name.
"parameter": {
"fetchSize":1024,//This configuration item defines the number of records fetched in batch each time between the plugin and the 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 allowed during synchronization.
},
"speed": {
"throttle":true,//When throttle is false, the mbps parameter does not take effect, indicating no rate limiting; when throttle is true, rate limiting is applied.
"concurrent":1 //Job concurrency.
"mbps":"12",//Rate limit, where 1mbps = 1MB/s.
}
},
"order": {
"hops": [
{
"from": "Reader",
"to": "Writer"
}
]
}
}
Parâmetros do script do Reader
|
Parâmetro |
Descrição |
Obrigatório |
Valor padrão |
|
datasource |
Nome da fonte de dados. O modo script permite adicionar fontes de dados. O valor deste parâmetro deve corresponder exatamente ao nome da fonte de dados adicionada. |
Sim |
Nenhum |
|
table |
Tabela a ser sincronizada, descrita em JSON. Nota
É necessário incluir table na unidade de configuração connection. |
Sim |
Nenhum |
|
fetchSize |
Define a quantidade de linhas buscadas em cada lote entre o plugin e o servidor de banco de dados. Esse valor determina o número de idas e vindas na rede entre o sistema de sincronização e o servidor, melhorando o desempenho da extração de dados. Nota
Um valor muito alto para fetchSize pode causar OOM durante a sincronização. Aumente-o gradualmente conforme a carga do ClickHouse. |
Não |
1.024 |
|
column |
Colunas do ClickHouse a serem lidas, separadas por vírgulas. Exemplo: Nota
O parâmetro column é obrigatório e não pode estar vazio. |
Sim |
Nenhum |
|
jdbcUrl |
String de conexão JDBC do banco de dados de origem. O jdbcUrl faz parte da unidade de configuração connection.
|
Sim |
Nenhum |
|
username |
Nome de usuário da fonte de dados. |
Sim |
Nenhum |
|
password |
Senha correspondente ao nome de usuário especificado na fonte de dados. |
Sim |
Nenhum |
|
splitPk |
Ao extrair dados do ClickHouse, definir splitPk indica o uso do campo representado por splitPk para fragmentar os dados. A sincronização inicia então tarefas simultâneas para aumentar a eficiência. Nota
Ao configurar splitPk, o parâmetro fetchSize torna-se obrigatório. |
Não |
Nenhum |
|
where |
Condição de filtro. Em cenários reais, é comum sincronizar os dados do dia atual definindo a condição where como A condição where viabiliza a sincronização incremental de negócios. Caso nenhuma instrução where seja fornecida — incluindo a ausência de chave ou valor para where —, o sistema trata a operação como sincronização completa. |
Não |
Nenhum |
Exemplo de script do Writer
{
"type":"job",
"version":"2.0",//Version number.
"steps":[
{
"stepType":"stream",
"parameter":{},
"name":"Reader",
"category":"reader"
},
{
"stepType":"clickhouse",//Plugin name.
"parameter":{
"username": "",
"password": "",
"column": [//Fields.
"id",
"name"
],
"connection": [
{
"table": [//Table name.
"ClickHouse_table"
],
"jdbcUrl": "jdbc:clickhouse://ip:port/database"
}
],
"preSql": [ //SQL statements executed before the data synchronization task runs.
"TRUNCATETABLEIFEXISTStablename"
],
"postSql": [//SQL statements executed after the data synchronization task runs.
"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, the mbps parameter does not take effect, indicating no rate limiting; when throttle is true, rate limiting is applied.
"concurrent":1, //Job concurrency.
"mbps":"12"//Rate limit, where 1mbps = 1MB/s.
}
},
"order":{
"hops":[
{
"from":"Reader",
"to":"Writer"
}
]
}
}
Parâmetros do script do Writer
|
Parâmetro |
Descrição |
Obrigatório |
Valor padrão |
|
jdbcUrl |
String de conexão JDBC do banco de dados de destino. O jdbcUrl integra a unidade de configuração connection.
|
Sim |
Nenhum |
|
username |
Nome de usuário da fonte de dados. |
Sim |
Nenhum |
|
password |
Senha associada ao nome de usuário informado na fonte de dados. |
Sim |
Nenhum |
|
table |
Nomes das tabelas de destino da escrita, descritos como um array JSON. Nota
Inclua table dentro da unidade de configuração connection. |
Sim |
Nenhum |
|
column |
Colunas da tabela de destino que receberão a escrita, separadas por vírgulas. Exemplo: Nota
O parâmetro column é obrigatório e não pode ficar vazio. |
Sim |
Nenhum |
|
preSql |
Instrução SQL padrão executada antes da gravação dos dados na tabela de destino. |
Não |
Nenhum |
|
postSql |
Instrução SQL padrão executada após a gravação dos dados na tabela de destino. |
Não |
Nenhum |
|
batchSize |
Quantidade de registros confirmados (committed) em cada lote. Esse valor reduz significativamente as idas e vindas na rede entre o sistema de sincronização e o ClickHouse, elevando o throughput geral. Definir um valor excessivamente alto pode provocar OOM durante a sincronização. |
Não |
1.024 |