Integração do Google Cloud Storage ao ClickHouse Cloud

O ClickPipe do GCS oferece uma maneira totalmente gerenciada e resiliente de fazer a ingestão de dados do Google Cloud Storage (GCS). Ele oferece suporte tanto à ingestão única quanto à ingestão contínua, com semântica exactly-once.

Os ClickPipes do GCS podem ser implantados e gerenciados manualmente pela UI do ClickPipes, bem como de forma programática usando OpenAPI e Terraform.

• JSON
• CSV
• TSV
• Parquet
• Avro

Por padrão, o ClickPipe do GCS carrega todos os arquivos que correspondem a um padrão do bucket especificado para a tabela de destino no ClickHouse em uma única operação em lote. Quando a tarefa de ingestão é concluída, o ClickPipe é interrompido automaticamente. Esse modo de ingestão única oferece semântica exactly-once, garantindo que cada arquivo seja processado de forma confiável e sem duplicatas.

Quando a ingestão contínua está ativada, o ClickPipes ingere continuamente dados do caminho especificado. Para determinar a ordem de ingestão, o ClickPipe do GCS usa, por padrão, a ordem lexicográfica implícita dos arquivos. Ele também pode ser configurado para fazer a ingestão de arquivos em qualquer ordem usando uma assinatura do Google Cloud Pub/Sub configurada para enviar notificações do bucket.

O GCS ClickPipe parte do pressuposto de que os arquivos são adicionados a um bucket em ordem lexicográfica e depende dessa ordem implícita para fazer a ingestão dos arquivos sequencialmente. Isso significa que qualquer novo arquivo deve ser lexicograficamente maior que o último arquivo ingerido. Por exemplo, arquivos chamados file1, file2 e file3 serão ingeridos em sequência, mas, se um novo file 0 for adicionado ao bucket, ele será ignorado, porque o nome do arquivo não é lexicograficamente maior que o do último arquivo ingerido.

Nesse modo, o GCS ClickPipe faz a carga inicial de todos os arquivos no caminho especificado e, em seguida, verifica periodicamente se há novos arquivos em um intervalo configurável (por padrão, 30 segundos). Para iniciar a ingestão contínua após um arquivo específico, configure Start after. O ClickPipes ignorará arquivos que forem lexicograficamente menores ou iguais ao valor configurado e continuará a ingerir arquivos mais novos a partir desse ponto.

É possível configurar um GCS ClickPipe para fazer a ingestão de arquivos que não tenham uma ordem implícita, configurando uma assinatura do Google Cloud Pub/Sub que receba notificações do bucket. Isso permite que o ClickPipes monitore eventos de criação de objetos e faça a ingestão de novos arquivos, independentemente da convenção de nomenclatura usada.

Nesse modo, o GCS ClickPipe faz uma carga inicial de todos os arquivos no caminho selecionado e, em seguida, monitora notificações OBJECT_FINALIZE via a assinatura do Pub/Sub que correspondam ao caminho especificado. Qualquer mensagem referente a um arquivo já visto, a um arquivo que não corresponda ao caminho ou a um evento de outro tipo será ignorada. Para fazer a ingestão apenas dos arquivos entregues por meio da assinatura, habilite Ignorar carga inicial. Quando habilitado, o ClickPipes ignora a varredura inicial dos arquivos existentes no caminho selecionado e processa apenas os arquivos entregues por meio da assinatura do Pub/Sub.

O Object Storage ClickPipes segue o padrão POSIX para correspondência de padrões de arquivos. Todos os padrões diferenciam maiúsculas de minúsculas e correspondem ao caminho completo após o nome do bucket. Para melhor desempenho, use o padrão mais específico possível (por exemplo, data-2024-*.csv em vez de *.csv).

Exemplos:

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

Exemplos:

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

Vários tipos de falhas podem ocorrer durante a ingestão de um grande volume de dados, o que pode resultar em inserções parciais ou dados duplicados. O Object Storage ClickPipes é resiliente a falhas de inserção e fornece semântica de exactly-once. Isso é feito com o uso de tabelas temporárias de staging. Os dados são primeiro inseridos nas tabelas de staging. Se algo der errado nessa inserção, a tabela de staging pode ser truncada, e a inserção pode ser repetida a partir de um estado limpo. Somente quando uma inserção é concluída com sucesso as partições da tabela de staging são movidas para a tabela de destino. Para saber mais sobre essa estratégia, confira esta postagem no blog.

Para rastrear quais arquivos foram submetidos à ingestão, inclua a coluna virtual _file na lista de mapeamento de colunas. A coluna virtual _file contém o nome do arquivo do objeto de origem, que pode ser usado para consultar quais arquivos já foram processados.

O ClickPipe do GCS oferece suporte a buckets públicos e privados. Buckets com Requester Pays não têm suporte.

A conta de serviço usada pelo ClickPipes deve permitir as seguintes ações no nível do bucket:

• roles/storage.objectViewer

Essa role contém as permissões IAM storage.objects.list e `storage.objects.get, que permitem ao ClickPipes listar e recuperar objetos no bucket especificado.

Ao usar o modo não ordenado, a conta de serviço deve ter os seguintes papéis na assinatura do Pub/Sub:

• roles/pubsub.subscriber — para receber e confirmar o recebimento de mensagens.
• roles/pubsub.viewer — para obter os metadados da assinatura.

A autenticação por conta de serviço é necessária ao usar o modo não ordenado com notificações do Pub/Sub. Selecione Service Account como método de autenticação e envie o arquivo JSON da chave da conta de serviço.

Para usar chaves HMAC na autenticação, escolha Credentials em Método de autenticação ao configurar a conexão do ClickPipe. Em seguida, informe a chave de acesso (por exemplo, GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) e a chave secreta (por exemplo, bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) nos campos Access key e Secret key, respectivamente.

Siga este guia para criar uma conta de serviço com uma chave HMAC.

Os ClickPipes do GCS usam dois caminhos de rede distintos para a descoberta de metadados e a ingestão de dados: o serviço ClickPipes e o serviço ClickHouse Cloud, respectivamente. Se você quiser configurar uma camada adicional de segurança de rede (por exemplo, por motivos de compliance), o acesso de rede deve ser configurado para ambos os caminhos.

• Para controle de acesso baseado em IP, as regras de filtragem de IP do seu GCS bucket devem permitir os IPs estáticos da região do serviço ClickPipes listados aqui, bem como os IPs estáticos do serviço ClickHouse Cloud. Para obter os IPs estáticos da sua região do ClickHouse Cloud, abra um terminal e execute:

  # Substitua <your-region> pela sua região do ClickHouse Cloud
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "<your-region>") | .egress_ips[]'

O ClickPipes vem com configurações padrão adequadas para a maioria dos casos de uso. Se o seu caso de uso exigir um ajuste mais fino, você poderá ajustar as seguintes configurações:

Os Object Storage ClickPipes são dimensionados com base no tamanho mínimo do serviço ClickHouse, determinado pelas configurações de autoscaling vertical. O tamanho do ClickPipe é definido quando o pipe é criado. Alterações posteriores nas configurações do serviço ClickHouse não afetam o tamanho do ClickPipe.

Para aumentar a taxa de transferência em jobs grandes de ingestão, recomendamos dimensionar o serviço ClickHouse antes de criar o ClickPipe.

O ClickPipes só tentará fazer a ingestão de objetos com 10 GB ou menos. Se um arquivo tiver mais de 10 GB, um erro será adicionado à tabela de erro dedicada do ClickPipes.

O ClickPipe do GCS usa a API XML do Cloud Storage para interoperabilidade, o que exige o uso do prefixo de bucket https://storage.googleapis.com/ (em vez de gs://) e de chaves HMAC para autenticação.

As visões materializadas na tabela de destino também são compatíveis. O ClickPipes criará tabelas de staging não apenas para a tabela de destino, mas também para qualquer visão materializada dependente.

Não criamos tabelas de staging para views não materializadas. Isso significa que, se você tiver uma tabela de destino com uma ou mais visões materializadas dependentes, essas visões materializadas devem evitar selecionar dados por meio de uma view da tabela de destino. Caso contrário, pode haver dados ausentes na visão materializada.