Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Template do Dataflow: BigQuery para ClickHouse

View as MarkdownEdit this pageReport an issueSet up docs MCP

O template do BigQuery para o ClickHouse é um pipeline em lote que faz a ingestão de dados de uma tabela do BigQuery para uma tabela no ClickHouse. O template pode ler a tabela inteira ou filtrar registros específicos usando uma consulta SQL fornecida.

Requisitos do pipeline

  • A tabela de origem no BigQuery deve existir.
  • A tabela de destino no ClickHouse deve existir.
  • O host do ClickHouse deve estar acessível a partir das máquinas worker do Dataflow.

Parâmetros do template



Nome do parâmetro Descrição do parâmetro Obrigatório Observações
jdbcUrl A URL JDBC do ClickHouse no formato jdbc:clickhouse://<host>:<port>/<schema>. ✅ Não adicione o nome de usuário nem a senha como opções JDBC. Qualquer outra opção JDBC pode ser adicionada ao final da URL JDBC. Para usuários do ClickHouse Cloud, adicione ssl=true&sslmode=NONE ao jdbcUrl.
clickHouseUsername O nome de usuário do ClickHouse para autenticação. ✅
clickHousePassword A senha do ClickHouse para autenticação. ✅
clickHouseTable A tabela ClickHouse de destino na qual os dados serão inseridos. ✅
maxInsertBlockSize O tamanho máximo do bloco para inserção, caso controlemos a criação de blocos para inserção (opção do ClickHouseIO). Uma opção do ClickHouseIO.
insertDistributedSync Se essa configuração estiver ativada, a consulta de inserção em distributed aguardará até que os dados sejam enviados para todos os nós do cluster. (opção do ClickHouseIO). Uma opção do ClickHouseIO.
insertQuorum Para consultas INSERT na tabela replicada, aguarda a gravação no número especificado de réplicas e lineariza a adição dos dados. 0 - desabilitado. Uma opção do ClickHouseIO. Essa configuração é desabilitada nas configurações padrão do servidor.
insertDeduplicate Para consultas INSERT na tabela replicada, especifica que a desduplicação dos blocos inseridos deve ser realizada. Uma opção do ClickHouseIO.
maxRetries Número máximo de tentativas por inserção. Uma opção do ClickHouseIO.
InputTableSpec A tabela do BigQuery da qual os dados serão lidos. Especifique inputTableSpec ou query. Quando ambos estiverem definidos, o parâmetro query terá precedência. Exemplo: <BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>. Lê dados diretamente do armazenamento do BigQuery usando a BigQuery Storage Read API. Esteja ciente das limitações da Storage Read API.
outputDeadletterTable A tabela do BigQuery para mensagens que não chegaram à tabela de saída. Se a tabela não existir, ela será criada durante a execução do pipeline. Se não for especificada, será usado <outputTableSpec>_error_records. Por exemplo, <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>.
query A consulta SQL a ser usada para ler dados do BigQuery. Se o conjunto de dados do BigQuery estiver em um projeto diferente do job do Dataflow, especifique o nome completo do conjunto de dados na consulta SQL, por exemplo: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. O padrão é GoogleSQL, a menos que useLegacySql seja true. Você deve especificar inputTableSpec ou query. Se definir ambos os parâmetros, o template usará o parâmetro query. Exemplo: SELECT * FROM sampledb.sample_table.
useLegacySql Defina como true para usar SQL legado. Esse parâmetro se aplica apenas ao usar o parâmetro query. O padrão é false.
queryLocation Necessário ao ler de uma view autorizada sem a permissão da tabela subjacente. Por exemplo, US.
queryTempDataset Defina um conjunto de dados existente para criar a tabela temporária que armazenará os resultados da consulta. Por exemplo, temp_dataset.
KMSEncryptionKey Ao ler do BigQuery usando a origem query, use esta chave do Cloud KMS para criptografar quaisquer tabelas temporárias criadas. Por exemplo, projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key.

Esquema das tabelas de origem e de destino

Para carregar corretamente o conjunto de dados do BigQuery no ClickHouse, o pipeline executa um processo de inferência de colunas com as seguintes fases:

  1. Os templates criam um objeto de esquema com base na tabela de destino do ClickHouse.
  2. Os templates percorrem o conjunto de dados do BigQuery e tentam fazer a correspondência das colunas com base em seus nomes.

Mapeamento de tipos de dados

Os tipos do BigQuery são convertidos com base na definição da sua tabela no ClickHouse. Portanto, a tabela acima mostra o mapeamento recomendado que você deve ter na sua tabela ClickHouse de destino (para uma determinada tabela/consulta do BigQuery):

Tipo do BigQuery Tipo do ClickHouse Observações
Tipo Array Tipo Array O tipo interno deve ser um dos tipos de dados primitivos compatíveis listados nesta tabela.
Tipo Boolean Tipo Bool
Tipo Date Tipo Date
Tipo Datetime Tipo Datetime Também funciona com Enum8, Enum16 e FixedString.
Tipo String Tipo String No BigQuery, todos os tipos Int (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) são aliases de INT64. Recomendamos que você defina no ClickHouse o tamanho de inteiro adequado, pois o modelo converterá a coluna com base no tipo de coluna definido (Int8, Int16, Int32, Int64).
Tipos Numeric - Integer Tipos Integer No BigQuery, todos os tipos Int (INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT) são aliases de INT64. Recomendamos que você defina no ClickHouse o tamanho de inteiro adequado, pois o modelo converterá a coluna com base no tipo de coluna definido (Int8, Int16, Int32, Int64). O modelo também converterá tipos Int sem sinal, se forem usados na tabela do ClickHouse (UInt8, UInt16, UInt32, UInt64).
Tipos Numeric - Float Tipos Float Tipos compatíveis no ClickHouse: Float32 e Float64

Executando o template

O template do BigQuery para o ClickHouse pode ser executado pela Google Cloud CLI.

Faça login no Google Cloud Console e procure por DataFlow.

  1. Clique no botão CREATE JOB FROM TEMPLATE
    console do DataFlow
  2. Quando o formulário do template abrir, informe um nome para o job e selecione a região desejada.
    formulário inicial do template do DataFlow
  3. No campo DataFlow Template, digite ClickHouse ou BigQuery e selecione o template BigQuery to ClickHouse
    Selecionar template BigQuery para ClickHouse
  4. Depois de selecionado, o formulário será expandido para que você possa fornecer detalhes adicionais:
    • A URL JDBC do servidor ClickHouse, no formato jdbc:clickhouse://host:port/schema.
    • O nome de usuário do ClickHouse.
    • O nome da tabela de destino do ClickHouse.

formulário expandido do template BigQuery para ClickHouse
  1. Personalize e adicione quaisquer configurações relacionadas ao BigQuery/ClickHouseIO, conforme detalhado na seção Parâmetros do template

Monitore o job

Acesse a aba Dataflow Jobs no Google Cloud Console para monitorar o status do job. Você verá os detalhes do job, incluindo o progresso e eventuais erros:

Console do Dataflow mostrando um job do BigQuery para o ClickHouse em execução

Solução de problemas

Erro de limite de memória (total) excedido (código 241)

Esse erro ocorre quando o ClickHouse fica sem memória ao processar grandes lotes de dados. Para resolver esse problema:

  • Aumente os recursos da instância: faça upgrade do seu servidor ClickHouse para uma instância maior, com mais memória, para suportar a carga de processamento de dados.
  • Reduza o tamanho do lote: ajuste o tamanho do lote na configuração do job do Dataflow para enviar fragmentos menores de dados ao ClickHouse, reduzindo o consumo de memória por lote. Essas mudanças podem ajudar a equilibrar o uso de recursos durante a ingestão de dados.

Código-fonte do template

O código-fonte do template está disponível em:

Navigation