Set up docs MCPPor padrão, o S3 ClickPipe pressupõe que os arquivos sejam adicionados a um bucket em ordem lexicográfica. É possível configurar um S3 ClickPipe 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 ObjectCreated:* e faça a ingestão de novos arquivos, independentemente da convenção de nomenclatura.
Como funciona
Nesse modo, o S3 ClickPipe faz uma carga inicial de todos os arquivos no caminho selecionado e, em seguida, passa a escutar eventos ObjectCreated:* na fila 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. A ingestão dos arquivos ocorre quando o limite configurado em max insert bytes ou max file count é atingido, ou após um intervalo configurável (por padrão, 30 segundos).
Para ingerir apenas arquivos entregues pela fila, habilite Ignorar carga inicial. Quando habilitada, essa opção faz com que o ClickPipes ignore a varredura inicial dos arquivos existentes no caminho selecionado e processe apenas os arquivos entregues pela fila SQS.
Vários tipos de falha podem ocorrer durante a ingestão de dados, o que pode resultar em inserções parciais ou dados duplicados. Os ClickPipes de armazenamento de objetos são resilientes a falhas de inserção e fornecem semântica exactly-once usando tabelas temporárias de staging. Os dados são primeiro inseridos em uma tabela de staging; se algo der errado, a tabela de staging é truncada e a inserção é repetida a partir de um estado limpo. Somente depois que uma inserção é concluída com sucesso as partições são movidas para a tabela de destino.
Criar uma fila do Amazon SQS
1. No Console da AWS, navegue até Simple Queue Service > Create queue. Use as configurações padrão para criar uma nova fila padrão.
2. Conecte seu bucket S3 à fila SQS usando uma das duas opções abaixo. O EventBridge é recomendado na maioria dos casos de uso porque oferece suporte a fan-out, filtragem de eventos mais flexível e não está sujeito à restrição do S3 de uma regra de notificação por tipo de evento, por prefixo.
a. Nas propriedades do bucket do S3, navegue até Event notifications > Amazon EventBridge e habilite o envio de notificações para o EventBridge. Clique em Save changes.
b. No Console da AWS, navegue até Amazon EventBridge > Rules > Create rule. Dê um nome à regra (por exemplo, S3ObjectCreated), escolha o barramento de eventos default e clique em Next. Na etapa Build event pattern, selecione AWS events or EventBridge partner events como origem do evento e, em seguida, insira manualmente o seguinte padrão de evento, substituindo <bucket-name> pelo nome do seu bucket:
{
"source": ["aws.s3"],
"detail-type": ["Object Created"],
"detail": {
"bucket": {
"name": ["<bucket-name>"]
}
}
}Opcionalmente, adicione uma condição object.key ao padrão para filtrar por prefixo ou sufixo. Se fizer isso, verifique se ela corresponde ao caminho definido para o ClickPipe.
c. Na etapa Select target(s), escolha AWS service como tipo de destino e selecione SQS queue. Selecione a fila criada na etapa anterior. Deixe Use execution role (recommended) marcado para que o EventBridge crie automaticamente a IAM role necessária e, em seguida, clique em Next e conclua o assistente.
d. Edite a política de acesso da fila do SQS para permitir que o EventBridge envie mensagens para ela. Substitua <sqs-queue-arn> e <eventbridge-rule-arn> pelos valores apropriados:
{
"Version": "2012-10-17",
"Id": "example-ID",
"Statement": [
{
"Sid": "AllowEventBridgeToSendMessage",
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": "SQS:SendMessage",
"Resource": "<sqs-queue-arn>",
"Condition": {
"ArnLike": {
"aws:SourceArn": "<eventbridge-rule-arn>"
}
}
}
]
}a. Edite a política de acesso da fila do SQS para permitir que seu bucket do S3 envie mensagens para ela. Substitua <sqs-queue-arn>, <bucket-arn> e <aws-account-id> pelos valores apropriados:
{
"Version": "2012-10-17",
"Id": "example-ID",
"Statement": [
{
"Sid": "AllowS3ToSendMessage",
"Effect": "Allow",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Action": "SQS:SendMessage",
"Resource": "<sqs-queue-arn>",
"Condition": {
"ArnLike": {
"aws:SourceArn": "<bucket-arn>"
},
"StringEquals": {
"aws:SourceAccount": "<aws-account-id>"
}
}
}
]
}b. Nas propriedades do bucket do S3, habilite Event notifications, selecione All object create events (s3:ObjectCreated:*) como tipo de evento e defina a fila do SQS como destino. Não selecione tipos de evento individuais: uploads podem emitir diferentes eventos ObjectCreated dependendo de como são realizados (por exemplo, uploads multipart emitem CompleteMultipartUpload em vez de Put), e arquivos cujo tipo de evento não for selecionado nunca serão entregues à fila. Opcionalmente, especifique um prefixo ou sufixo para filtrar quais objetos acionam notificações — se fizer isso, verifique se ele corresponde ao caminho definido para o ClickPipe.
Configure uma função do IAM
1. No console do ClickHouse Cloud, navegue até Settings > Network security information e copie o ARN da função do IAM do seu serviço.
2. No Console da AWS, navegue até IAM > Roles > Create role. Escolha Custom trust policy e cole o texto a seguir, substituindo <ch-cloud-arn> pelo ARN da função do IAM copiado na etapa anterior:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAssumeRole",
"Effect": "Allow",
"Principal": {
"AWS": "<ch-cloud-arn>"
},
"Action": "sts:AssumeRole"
}
]
}3. Crie uma política inline para a função do IAM com as permissões necessárias para ler objetos no S3 e gerenciar mensagens na fila do SQS. Substitua <bucket-arn> e <sqs-queue-arn> pelos valores apropriados:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3BucketMetadataAccess",
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:ListBucket"
],
"Resource": "<bucket-arn>"
},
{
"Sid": "AllowGetListObjects",
"Effect": "Allow",
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": "<bucket-arn>/*"
},
{
"Sid": "SQSNotificationsAccess",
"Effect": "Allow",
"Action": [
"sqs:DeleteMessage",
"sqs:ListQueues",
"sqs:ReceiveMessage",
"sqs:GetQueueAttributes"
],
"Resource": "<sqs-queue-arn>"
}
]
}Crie um ClickPipe com modo não ordenado
1. No console do ClickHouse Cloud, navegue até Fontes de dados > Criar ClickPipe e selecione Amazon S3. Insira os detalhes para se conectar ao seu bucket do S3. Em Método de autenticação, escolha IAM role e informe o ARN da role que você criou na etapa anterior.
2. Em Dados de entrada, ative Ingestão contínua. Selecione Qualquer ordem como modo de ingestão e informe a URL da fila do SQS da fila conectada ao seu bucket. Para processar apenas arquivos da fila e ignorar a varredura inicial dos arquivos existentes no caminho selecionado, habilite Ignorar carregamento inicial. A fila deve ser usada exclusivamente por este ClickPipe — consulte Criar uma fila do Amazon SQS.
3. Em Informações de parsing, defina uma Chave de ordenação para a tabela de destino. Faça os ajustes necessários no esquema mapeado e, em seguida, configure uma role para o usuário do banco de dados do ClickPipes.
4. Revise a configuração e clique em Criar ClickPipe. A menos que Ignorar carregamento inicial esteja habilitado, o ClickPipes fará uma varredura inicial no seu bucket para carregar todos os arquivos existentes que correspondam ao caminho especificado e, em seguida, começará a processar os arquivos à medida que eventos ObjectCreated:* correspondentes forem entregues pela fila.