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

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

# Biblioteca cliente de C++

`clickhouse-cpp` es la biblioteca cliente oficial de C++ para ClickHouse, que proporciona una interfaz rápida y con tipado seguro
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 funcionalidades y tipos de datos aún no estén totalmente implementados o no sean compatibles.

  Sus comentarios son muy valiosos y ayudan a orientar la priorización de nuevas funcionalidades y
  mejoras. Si encuentra limitaciones, funcionalidades ausentes o comportamientos inesperados, por favor
  comparta sus observaciones o solicitudes de funcionalidades a través del gestor 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 su proyecto
</div>

La forma más sencilla de incorporar la biblioteca a su proyecto es usar el módulo
`FetchContent` de CMake. Este enfoque le permite fijar una versión concreta de la biblioteca y
compilarla como parte de su flujo de trabajo habitual con 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 en conexiones sin TLS,
por lo general se recomienda habilitarla.

La compilación con compatibilidad con SSL requiere que los paquetes de desarrollo de OpenSSL estén instalados. 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 objetivo con el objetivo 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 cliente
</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">
  ### Creación de tablas y ejecución de consultas sin datos
</div>

Para ejecutar una consulta que no devuelve datos, como al 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 añaden 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">
  ### Selección de datos
</div>

Para ejecutar una consulta que devuelva datos, use el método `Select` y proporcione una función de devolución de llamada 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`