O ClickPipe para S3 oferece uma maneira totalmente gerenciada e resiliente de realizar a ingestão de dados do Amazon S3 e de serviços de armazenamento de objetos compatíveis com S3 para o ClickHouse Cloud. Ele oferece suporte tanto à ingestão única quanto à ingestão contínua, com semântica de exactly-once.
Os ClickPipes para S3 podem ser implantados e gerenciados manualmente pela UI do ClickPipes, bem como de forma programática usando OpenAPI e Terraform.
Fontes de dados compatíveis
Devido às diferenças nos formatos de URL e nas implementações de API entre provedores de armazenamento de objetos, nem todos os serviços compatíveis com S3 são suportados nativamente. Se você estiver enfrentando problemas com um serviço que não está listado acima, entre em contato com nossa equipe. file1, file2 e file3 serão ingeridos sequencialmente, 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 S3 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). Não é possível iniciar a ingestão a partir de um arquivo específico ou de um ponto no tempo — o ClickPipes sempre carregará todos os arquivos no caminho especificado.
É possível configurar um ClickPipe do S3 para fazer a ingestão de arquivos que não tenham uma ordem implícita, configurando uma fila do Amazon SQS conectada ao bucket e, opcionalmente, usando o Amazon EventBridge como roteador de eventos. Isso permite que o ClickPipes escute eventos de criação de objetos e faça a ingestão de novos arquivos, independentemente da convenção de nomenclatura adotada.
O modo não ordenado é compatível apenas com o Amazon S3 e não é compatível com buckets públicos nem com serviços compatíveis com S3. Ele exige a configuração de uma fila do Amazon SQS conectada ao bucket e, opcionalmente, o uso do Amazon EventBridge como roteador de eventos. ObjectCreated:* na fila que correspondam ao caminho especificado. Qualquer mensagem referente a um arquivo já processado, a um arquivo que não corresponda ao caminho ou a um evento de outro tipo será ignorada.
Definir um prefixo/sufixo para eventos é opcional. Se fizer isso, verifique se ele corresponde ao caminho definido para o ClickPipe. O S3 não permite várias regras de notificação sobrepostas para os mesmos tipos de evento.
max insert bytes ou max file count é atingido, ou após um intervalo configurável (por padrão, 30 segundos). Não é possível iniciar a ingestão a partir de um arquivo específico ou de um ponto específico no tempo — o ClickPipes sempre carregará todos os arquivos no caminho selecionado. Se uma DLQ estiver configurada, as mensagens com falha serão reenfileiradas e reprocessadas até o número de vezes configurado no parâmetro maxReceiveCount da DLQ.
Recomendamos fortemente configurar uma Dead-Letter-Queue (DLQ) para a fila do SQS, para facilitar a depuração e a nova tentativa de processamento de mensagens com falha.
EventBridge para SQS
Também é possível enviar notificações de eventos do S3 para o SQS por meio do Amazon EventBridge. Essa é a abordagem recomendada para a maioria dos casos de uso, pois o EventBridge oferece suporte a uma filtragem de eventos mais avançada, ao envio para vários destinos e não está sujeito à limitação do S3 de permitir apenas uma regra de notificação por tipo de evento para cada prefixo. Consulte Configuração do modo não ordenado para ingestão contínua para ver instruções passo a passo.
SNS para SQS
Também é possível enviar notificações de eventos do S3 para o SQS por meio de um tópico do SNS. Isso pode ser útil caso você encontre algumas das limitações da integração direta S3 → SQS. Nesse caso, será necessário habilitar a opção de entrega de mensagens brutas.
Correspondência de padrões de arquivo
data-2024-*.csv em vez de *.csv).
Exemplos:
https://bucket.s3.amazonaws.com/folder/*.csvhttps://bucket.s3.amazonaws.com/logs/**/data.jsonhttps://bucket.s3.amazonaws.com/file-?.parquethttps://bucket.s3.amazonaws.com/data-2024-*.csv.gz
Exemplos:
https://bucket.s3.amazonaws.com/{documents-01,documents-02}.jsonhttps://bucket.s3.amazonaws.com/file-{1..100}.csvhttps://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet
Semântica de exactly-once
_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 em consultas para identificar quais arquivos já foram processados.
O ClickPipe do S3 oferece suporte a buckets públicos e privados. Buckets Requester Pays não têm suporte.
Os buckets devem permitir as seguintes ações na política do bucket:
Ao usar o modo não ordenado, o SQS deve permitir as seguintes ações na política da fila:
Para usar chaves de acesso para autenticação, escolha Credentials em Método de autenticação ao configurar a conexão do ClickPipe. Em seguida, informe o ID da chave de acesso (por exemplo, AKIAIOSFODNN7EXAMPLE) e a chave de acesso secreta (por exemplo, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) em Access key e Secret key, respectivamente.
Para usar controle de acesso baseado em funções na autenticação, escolha IAM role em Método de autenticação ao configurar a conexão do ClickPipe.
Siga este guia para criar uma função com a política de confiança necessária para acessar o S3. Em seguida, informe o ARN da função do IAM em IAM role ARN.
Os ClickPipes do S3 usam dois caminhos de rede distintos para descoberta de metadados e 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 conformidade), o acesso à rede deve ser configurado para ambos os caminhos.
-
Para controle de acesso baseado em IP, a política do bucket do S3 deve 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:
-
Para controle de acesso baseado em endpoint de VPC, o bucket do S3 deve estar na mesma região que o serviço ClickHouse Cloud e restringir as operações
GetObject aos IDs dos endpoints de VPC do serviço ClickHouse Cloud. Para obter os endpoints de VPC da sua região do ClickHouse Cloud, abra um terminal e execute:
O ClickPipes fornece padrões sensatos que atendem aos requisitos da maioria dos casos de uso. Se o seu caso de uso exigir ajustes adicionais, você poderá ajustar as seguintes configurações:
Os ClickPipes de armazenamento de objetos são dimensionados com base no tamanho mínimo do serviço ClickHouse determinado pelas configurações definidas de autoscaling vertical. O tamanho do ClickPipe é determinado quando o pipe é criado. Alterações subsequentes nas configurações do serviço ClickHouse não afetarão o tamanho do ClickPipe.
Para aumentar a vazão em grandes trabalhos de ingestão, recomendamos escalar 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 erros dedicada do ClickPipes.
Embora sejam compatíveis com S3, alguns serviços usam uma estrutura de URL diferente que o ClickPipe para S3 talvez não consiga interpretar (por exemplo, o Backblaze B2) ou exigem integração com serviços de fila específicos do provedor para ingestão contínua e não ordenada. Se você estiver enfrentando problemas com um serviço que não esteja listado em fontes de dados compatíveis, entre em contato com nossa equipe.
VIEWs 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 VIEW 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 VIEWs materializadas downstream, essas VIEWs materializadas devem evitar selecionar dados por meio de uma VIEW da tabela de destino. Caso contrário, poderá haver dados ausentes na VIEW materializada. 
