> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentación de la biblioteca cliente de ClickHouse para C++ y su integración con el framework u-server

# Biblioteca cliente en C++

`clickhouse-cpp` es la biblioteca cliente oficial de ClickHouse para C++, que proporciona una
interfaz rápida y con seguridad de tipos para ClickHouse mediante su protocolo binario nativo.

Las instrucciones de compilación, los ejemplos de uso y la documentación adicional están disponibles en el
repositorio de GitHub del proyecto: [https://github.com/ClickHouse/clickhouse-cpp](https://github.com/ClickHouse/clickhouse-cpp).

<Note>
  La biblioteca está en desarrollo activo. Aunque ya admite la funcionalidad principal de ClickHouse,
  es posible que algunas características y tipos de datos aún no estén completamente implementados o no sean compatibles.

  Sus comentarios son muy valiosos y ayudan a orientar la priorización de nuevas características y
  mejoras. Si encuentra limitaciones, funciones faltantes o un comportamiento inesperado, por favor
  comparta sus observaciones o solicitudes de nuevas características a través del rastreador de incidencias en 
  [https://github.com/ClickHouse/clickhouse-cpp/issues](https://github.com/ClickHouse/clickhouse-cpp/issues)
</Note>

<div id="including-library-into-project">
  ## Incluir la biblioteca en tu proyecto
</div>

La forma más sencilla de incorporar la biblioteca a tu proyecto es usar el módulo
`FetchContent` de CMake. Este enfoque te permite fijar una versión exacta de la biblioteca y
compilarla como parte de tu flujo de trabajo habitual en CMake.

```cmake theme={null}
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   # también puede ser `master` u otra rama
)
FetchContent_MakeAvailable(clickhouse-cpp)
```

La opción `WITH_OPENSSL` habilita la compatibilidad con TLS en la biblioteca y es necesaria al conectarse a
ClickHouse Cloud u otros despliegues de ClickHouse con SSL habilitado. Aunque puede omitirse para conexiones sin TLS,
en general se recomienda habilitarla.

Compilar con compatibilidad con SSL requiere que estén instalados los paquetes de desarrollo de OpenSSL. Instale
`libssl-dev` en Debian, Ubuntu o sus derivados; `openssl-devel` en Fedora, Red Hat; o
`openssl` en macOS, usando Homebrew.

Una vez que la dependencia esté disponible, enlace su target con el target de biblioteca exportado:

```cmake theme={null}
target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)
```

<div id="examples">
  ## Ejemplos
</div>

<div id="example-setup-client">
  ### Configuración del objeto Client
</div>

Cree una instancia de `Client` para establecer una conexión con ClickHouse. El siguiente ejemplo
muestra cómo conectarse a una instancia local de ClickHouse, donde no se requiere contraseña y SSL no está
habilitado.

```cpp theme={null}
#include <clickhouse/client.h>

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

En configuraciones más avanzadas, se requiere una configuración adicional. El siguiente ejemplo muestra
cómo conectarse a una instancia de ClickHouse Cloud usando varios parámetros adicionales:

```cpp theme={null}
#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 conexiones SSL, ClickHouse Cloud usa el puerto 9440
    };
```

<div id="example-create-table">
  ### Crear tablas y ejecutar consultas sin datos
</div>

Para ejecutar una consulta que no devuelva ningún dato, como crear tablas, use el método `Execute`.
El mismo enfoque se aplica a otras sentencias como `ALTER TABLE`, `DROP`, etc.

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

<div id="example-insert-data">
  ### Inserción de datos
</div>

Para insertar datos en una tabla, construya un `Block` y complételo con objetos de columna que coincidan con el
esquema de la tabla. Los datos se agregan columna por columna y luego se insertan en una sola operación mediante el
método `Insert`, que está optimizado para inserciones por lotes eficientes.

```cpp theme={null}
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);
```

<div id="example-select">
  ### Seleccionar los datos
</div>

Para ejecutar una consulta que devuelva datos, use el método `Select` y proporcione una función de callback para procesar el
resultado. Los resultados de la consulta se entregan como objetos `Block`, lo que refleja la representación de datos nativa
orientada a columna de ClickHouse.

```cpp theme={null}
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";
        }
    });
```

<div id="supported-data-types">
  ## Tipos de datos compatibles
</div>

* `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)` y `LowCardinality(FixedString(N))`
* `Nullable(T)`
* `Array(T)`
* `Tuple`
* `Map`
* `IPv4`, `IPv6`
* `Point`, `Ring`, `Polygon`, `MultiPolygon`