Biblioteca cliente C++

Documentação da biblioteca cliente C++ do ClickHouse e da integração com o framework u-server

clickhouse-cpp é a biblioteca cliente C++ oficial do ClickHouse, oferecendo uma interface rápida e com segurança de tipos para o ClickHouse por meio de seu protocolo binário nativo.

As instruções de compilação, os exemplos de uso e a documentação adicional estão disponíveis no repositório GitHub do projeto: https://github.com/ClickHouse/clickhouse-cpp.

A biblioteca está em desenvolvimento ativo. Embora já ofereça suporte às principais funcionalidades do ClickHouse, alguns recursos e tipos de dados talvez ainda não estejam totalmente implementados ou não tenham suporte completo.

Seu feedback é muito valioso e ajuda a orientar a priorização de novos recursos e melhorias. Se você encontrar limitações, funcionalidades ausentes ou comportamento inesperado, por favor compartilhe suas observações ou solicitações de novos recursos pelo rastreador de issues em  https://github.com/ClickHouse/clickhouse-cpp/issues

​

Incluindo a biblioteca ao seu projeto

A forma mais simples de incorporar a biblioteca ao seu projeto é usando o módulo FetchContent do CMake. Essa abordagem permite fixar uma versão exata da biblioteca e compilá-la como parte do fluxo de trabalho normal do CMake.

include(FetchContent)

set(WITH_OPENSSL YES CACHE BOOL "Enable OpenSSL in clickhouse-cpp" FORCE)
FetchContent_Declare(
    clickhouse-cpp
    GIT_REPOSITORY https://github.com/ClickHouse/clickhouse-cpp.git
    GIT_TAG v2.6.0   # também pode ser `master` ou outro branch
)
FetchContent_MakeAvailable(clickhouse-cpp)

A opção WITH_OPENSSL habilita o suporte a TLS na biblioteca e é necessária ao se conectar ao ClickHouse Cloud ou a outras implantações do ClickHouse com SSL habilitado. Embora possa ser omitida em conexões sem TLS, geralmente é recomendável habilitá-la.

A compilação com suporte a SSL exige que os pacotes de desenvolvimento do OpenSSL estejam instalados. Instale libssl-dev no Debian, Ubuntu ou seus derivados; openssl-devel no Fedora e Red Hat; ou openssl no macOS, usando o Homebrew.

Depois que a dependência estiver disponível, vincule seu target ao target de biblioteca exportado:

target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)

​

Exemplos

​

Definindo o objeto cliente

Crie uma instância de Client para estabelecer uma conexão com o ClickHouse. O exemplo a seguir mostra como se conectar a uma instância local do ClickHouse, na qual não é necessário usar senha e o SSL não está habilitado.

#include <clickhouse/client.h>

clickhouse::Client client{clickhouse::ClientOptions().SetHost("localhost")};

Em configurações mais avançadas, é necessária uma configuração adicional. O exemplo a seguir demonstra como se conectar a uma instância do ClickHouse Cloud usando vários parâmetros adicionais:

#include <clickhouse/client.h>

clickhouse::Client client{
    clickhouse::ClientOptions{}
      .SetHost("your.instance.clickhouse.cloud")
      .SetUser("default")
      .SetPassword("your-password")
      .SetSSLOptions({})   // Habilitar SSL
      .SetPort(9440)       // para conexões via SSL, o ClickHouse Cloud usa a porta 9440
    };

​

Criando tabelas e executando consultas sem retorno de dados

Para executar uma consulta que não retorna dados, como na criação de tabelas, use o método Execute. A mesma abordagem se aplica a outras instruções, como ALTER TABLE, DROP etc.

client.Execute(R"(
    CREATE TABLE IF NOT EXISTS greetings (
        id UInt64,
        message String,
        language String) 
    ENGINE = MergeTree ORDER BY id)");

​

Inserindo dados

Para inserir dados em uma tabela, construa um Block e preencha-o com objetos de coluna que correspondam ao esquema da tabela. Os dados são adicionados coluna por coluna e, em seguida, inseridos em uma única operação usando o método Insert, que é otimizado para gravações em lote eficientes.

auto id = std::make_shared<clickhouse::ColumnUInt64>();
auto message = std::make_shared<clickhouse::ColumnString>();
auto language = std::make_shared<clickhouse::ColumnString>();

id->Append(1);
message->Append("Hello, World!");
language->Append("English");

id->Append(2);
message->Append("¡Hola, Mundo!");
language->Append("Spanish");

id->Append(3);
message->Append("Hallo wereld!");
language->Append("Dutch");

clickhouse::Block block{};
block.AppendColumn("id", id);
block.AppendColumn("message", message);
block.AppendColumn("language", language);

client.Insert("greetings", block);

​

Selecionando os dados

Para executar uma consulta que retorna dados, use o método Select e forneça um callback para processar o resultado. Os resultados da consulta são retornados como objetos Block, refletindo a representação de dados nativa e orientada a colunas do ClickHouse.

client.Select(
    "SELECT id, message, language FROM greetings",
    [](const clickhouse::Block & block){
        for (size_t i = 0; i < block.GetRowCount(); ++i) {
            auto id = block[0]->AsStrict<clickhouse::ColumnUInt64>()->At(i);
            auto message = block[1]->AsStrict<clickhouse::ColumnString>()->At(i);
            auto language = block[2]->AsStrict<clickhouse::ColumnString>()->At(i);
            std::cout << id << "\t" << message << "\t" << language << "\n";
        }
    });

​

Tipos de dados suportados

• UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64
• UInt128, Int128
• Decimal32, Decimal64, Decimal128
• Float32, Float64
• Date
• DateTime, DateTime64
• DateTime([timezone]), DateTime64(N, [timezone])
• UUID
• Enum8, Enum16
• String
• FixedString(N)
• LowCardinality(String) e LowCardinality(FixedString(N))
• Nullable(T)
• Array(T)
• Tuple
• Map
• IPv4, IPv6
• Point, Ring, Polygon, MultiPolygon