Usando a interface HTTP do ClickHouse no Azure Data Factory

A função de tabela azureBlobStorage é uma forma rápida e conveniente de fazer a ingestão de dados do Azure Blob Storage para o ClickHouse. No entanto, nem sempre ela é a opção mais adequada pelos seguintes motivos:

• Seus dados podem não estar armazenados no Azure Blob Storage — por exemplo, podem estar no Azure SQL Database, Microsoft SQL Server ou Cosmos DB.
• As políticas de segurança podem impedir completamente o acesso externo ao Blob Storage — por exemplo, se a conta de armazenamento estiver bloqueada e sem endpoint público.

Nesses cenários, você pode usar o Azure Data Factory junto com a interface HTTP do ClickHouse para enviar dados de serviços do Azure para o ClickHouse.

Esse método inverte o fluxo: em vez de o ClickHouse extrair os dados do Azure, o Azure Data Factory envia os dados ao ClickHouse. Essa abordagem normalmente exige que sua instância do ClickHouse esteja acessível pela internet pública.

O Azure Data Factory oferece suporte ao envio de dados para sistemas externos via HTTP no formato JSON. Podemos usar esse recurso para inserir dados diretamente no ClickHouse usando a interface HTTP do ClickHouse. Saiba mais na documentação da interface HTTP do ClickHouse .

Para este exemplo, só precisamos especificar a tabela de destino, definir o formato dos dados de entrada como JSON e incluir opções para permitir uma interpretação de timestamp mais flexível.

INSERT INTO my_table
SETTINGS 
    date_time_input_format='best_effort',
    input_format_json_read_objects_as_strings=1
FORMAT JSONEachRow

Para enviar esta consulta como parte de uma requisição HTTP, basta passá-la como uma string com codificação de URL para o parâmetro query no endpoint do ClickHouse:

https://your-clickhouse-url.com?query=INSERT%20INTO%20my_table%20SETTINGS%20date_time_input_format%3D%27best_effort%27%2C%20input_format_json_read_objects_as_strings%3D1%20FORMAT%20JSONEachRow%0A

Agora você pode enviar dados em formato JSON para esta URL. Os dados devem corresponder à estrutura da tabela de destino. Veja um exemplo simples usando curl, considerando uma tabela com três colunas: col_1, col_2 e col_3.

curl \
    -XPOST "https://your-clickhouse-url.com?query=<our_URL_encded_query>" \
    --data '{"col_1":9119,"col_2":50.994,"col_3":"2019-06-01 00:00:00"}'

Você também pode enviar um array JSON de objetos ou JSON Lines (objetos JSON delimitados por quebras de linha). O Azure Data Factory usa o formato de array JSON, que funciona perfeitamente com a entrada JSONEachRow do ClickHouse.

Como você pode ver, nesta etapa não é necessário fazer nada de especial no lado do ClickHouse. A interface HTTP já oferece tudo o que é necessário para atuar como um endpoint no estilo REST — nenhuma configuração adicional é necessária.

Agora que fizemos o ClickHouse se comportar como um endpoint REST, é hora de configurar o Azure Data Factory para usá-lo.

Nas próximas etapas, vamos criar uma instância do Azure Data Factory, configurar um Linked Service para a sua instância do ClickHouse, definir um Dataset para o sink REST e criar uma atividade Copy Data para enviar dados do Azure para o ClickHouse.

Este guia pressupõe que você tenha acesso a uma conta do Microsoft Azure e já tenha configurado uma assinatura e um grupo de recursos. Se você já tiver um Azure Data Factory configurado, poderá pular esta etapa com segurança e seguir para a próxima usando o serviço existente.

1. Faça login no Microsoft Azure Portal e clique em Criar um recurso.

   

2. No painel Categorias à esquerda, selecione Analytics e, em seguida, clique em Data Factory na lista de serviços populares.

   

3. Selecione sua assinatura e seu grupo de recursos, insira um nome para a nova instância do Data Factory, escolha a região e mantenha a versão como V2.

   

4. Clique em Revisar + criar e, depois, em Criar para iniciar a implantação.

   

   

Quando a implantação for concluída com sucesso, você poderá começar a usar sua nova instância do Azure Data Factory.

1. Faça login no Microsoft Azure Portal e abra sua instância do Data Factory.

   

2. Na página Overview do Data Factory, clique em Launch Studio.

   

3. No menu à esquerda, selecione Manage e depois vá para Linked services, então clique em + Novo para criar um novo linked service.

   

4. Na barra de pesquisa do novo linked service, digite REST, selecione REST e clique em Continue para criar uma instância de um conector REST.

   

5. No painel de configuração do linked service, insira um nome para o novo serviço, clique no campo Base URL e depois em Add dynamic content (esse link só aparece quando o campo está selecionado).

   

6. No painel de conteúdo dinâmico, você pode criar uma URL parametrizada, o que permite definir a consulta depois, ao criar datasets para diferentes tabelas — isso torna o linked service reutilizável.

   

7. Clique no "+" ao lado do campo de filtro e adicione um novo parâmetro, nomeando-o como pQuery, defina o tipo como String e o valor padrão como SELECT 1. Clique em Save.

   

8. No campo de expressão, insira o texto a seguir e clique em OK. Substitua your-clickhouse-url.com pelo endereço real da sua instância do ClickHouse.

   @{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}

   

9. De volta ao formulário principal, selecione autenticação básica, insira o nome de usuário e a senha usados para se conectar à sua interface HTTP do ClickHouse e clique em Test connection. Se tudo estiver configurado corretamente, você verá uma mensagem de sucesso.

   

10. Clique em Create para finalizar a configuração.

    

Agora você deverá ver o linked service baseado em REST recém-registrado na lista.

Agora que temos um linked service configurado para a interface HTTP do ClickHouse, podemos criar um conjunto de dados que o Azure Data Factory usará para enviar dados ao ClickHouse.

Neste exemplo, vamos inserir uma pequena amostra do conjunto Environmental Sensors Data.

1. Abra o console de consultas do ClickHouse de sua preferência — pode ser a interface web do ClickHouse Cloud, o cliente de linha de comando ou qualquer outra interface que você use para executar consultas — e crie a tabela de destino:

   CREATE TABLE sensors
   (
       sensor_id UInt16,
       lat Float32,
       lon Float32,
       timestamp DateTime,
       temperature Float32
   )
   ENGINE = MergeTree
   ORDER BY (timestamp, sensor_id);

2. No Azure Data Factory Studio, selecione Author no painel à esquerda. Passe o cursor sobre o item conjunto de dados, clique no ícone de três pontos e escolha New dataset.

   

3. Na barra de pesquisa, digite REST, selecione REST e clique em Continue. Digite um nome para o conjunto de dados e selecione o linked service que você criou na etapa anterior. Clique em OK para criar o conjunto de dados.

   

4. Agora você deverá ver o conjunto de dados recém-criado listado na seção Datasets no painel Factory Resources à esquerda. Selecione o conjunto de dados para abrir as propriedades dele. Você verá o parâmetro pQuery que foi definido no linked service. Clique no campo de texto Value. Em seguida, clique em Add dynamic content.

   

5. No painel que se abrir, cole a seguinte consulta:

   INSERT INTO sensors
   SETTINGS 
       date_time_input_format=''best_effort'', 
       input_format_json_read_objects_as_strings=1 
   FORMAT JSONEachRow

6. Clique em OK para salvar a expressão. Clique em Test connection. Se tudo estiver configurado corretamente, você verá a mensagem Connection successful. Clique em Publish all no topo da página para salvar suas alterações.

   

Neste exemplo, não usaremos o Environmental Sensors Dataset completo, mas apenas um pequeno subconjunto disponível em Sensors Dataset Sample.

Envie o conjunto de dados para o seu Azure Blob Storage (ou outro serviço de armazenamento de sua preferência). Em seguida, no Azure Data Factory Studio, vá para o painel Factory Resources. Crie um novo conjunto de dados que aponte para os dados enviados. Clique em Publish all para salvar suas alterações.

Agora que configuramos os conjuntos de dados de entrada e saída, podemos configurar uma atividade de Copy Data para transferir dados do nosso conjunto de dados de exemplo para a tabela sensors no ClickHouse.

1. Abra o Azure Data Factory Studio e vá para a guia Author. No painel Factory Resources, passe o cursor sobre Pipeline, clique no ícone de três pontos e selecione New pipeline.

   

2. No painel Activities, expanda a seção Move and transform e arraste a atividade Copy data para a tela.

   

3. Selecione a guia Source e escolha o conjunto de dados de origem que você criou anteriormente.

   

4. Vá para a guia Sink e selecione o conjunto de dados do ClickHouse criado para a tabela sensors. Defina Request method como POST. Certifique-se de que HTTP compression type esteja definido como None.

5. Clique em Debug na parte superior da tela para executar o pipeline. Após uma breve espera, a atividade entrará na fila e será executada. Se tudo estiver configurado corretamente, a tarefa deverá terminar com status Success.

   

6. Quando concluir, clique em Publish all para salvar as alterações no pipeline e no conjunto de dados.

• Interface HTTP
• Copiar e transformar dados de um endpoint REST e para ele usando o Azure Data Factory
• Seleção de uma estratégia de insert
• Criar e configurar um runtime de integração auto-hospedado