Todos os produtos
Search
Central de documentação

DataWorks:Fonte de dados ClickHouse

Última atualização: Jun 27, 2026

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

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: "column": ["id", "name", "age"].

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.

  • Configure apenas um valor por banco de dados.

  • O formato do jdbcUrl segue o padrão oficial do ClickHouse e pode conter parâmetros adicionais. Exemplo: jdbc:clickhouse://localhost:3306/test?user=root&password=&useUnicode=true&characterEncoding=gbk &autoReconnect=true&failOverReadOnly=false.

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 gmt_create>$bizdate.

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.

  • Configure apenas um valor por banco de dados.

  • O formato de jdbcUrl segue o padrão oficial do ClickHouse e pode incluir parâmetros extras. Por exemplo: jdbc:clickhouse://127.0.0.1:3306/database.

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: "column": ["id", "name", "age"].

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