()` antes de serializarse. Si se intenta serializar un tipo no registrado, se lanza `ClickHouseJsonSerializationException`.
* Las propiedades de diccionario y array/lista requieren indicaciones de tipo en la definición de la columna para serializarse correctamente. Sin esas indicaciones, use el modo String.
* Los valores NULL en las propiedades POCO solo se escriben cuando la ruta tiene una indicación de tipo `Nullable(T)` en la definición de la columna. ClickHouse no permite tipos `Nullable` dentro de rutas JSON dinámicas, por lo que las propiedades con valor NULL sin indicación se omiten.
* Los atributos `ClickHouseJsonPath` y `ClickHouseJsonIgnore` se ignoran en modo String (solo funcionan en modo Binary).
***
#### Otros tipos
| Tipo de ClickHouse | Tipos de .NET aceptados | Notas |
| ----------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| UUID | `Guid`, `string` | La cadena se interpreta como `Guid` |
| IPv4 | `IPAddress`, `string` | Debe ser IPv4; la cadena se analiza con `IPAddress.Parse()` |
| IPv6 | `IPAddress`, `string` | Debe ser IPv6; la cadena se analiza con `IPAddress.Parse()` |
| Nothing | Any | No escribe nada (no-op) |
| Dynamic | — | **No admitido** (lanza `NotImplementedException`) |
| Array(T) | `IList`, `null` | `null` escribe un array vacío |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | El número de elementos debe coincidir con la aridad de la tupla |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull`, o tipos aceptados por T | Escribe un byte indicador de null antes del valor |
| Enum8 | `string`, `sbyte`, tipos numéricos | La cadena se busca en el diccionario del enum |
| Enum16 | `string`, `short`, tipos numéricos | La cadena se busca en el diccionario del enum |
| LowCardinality(T) | Tipos aceptados por T | Se delega en el tipo subyacente |
| SimpleAggregateFunction | Tipos aceptados por el tipo subyacente | Se delega en el tipo subyacente |
| Nested(...) | `IList` de tuplas | El número de elementos debe coincidir con el número de campos |
| Variant(T1, T2, ...) | Valor que coincida con uno de T1, T2, ... | Lanza `ArgumentException` si no coincide ningún tipo |
| QBit(T, dim) | `IList` | Se delega en Array; la dimensión es solo metadatos |
***
#### Tipos de geometría
| Tipo de ClickHouse | Tipos de .NET aceptados | Notas |
| ------------------ | ------------------------------------------------------- | ---------------------------------------- |
| Point | `System.Drawing.Point`, `ITuple`, `IList` (2 elementos) | |
| Ring | `IList` de `Point` | |
| LineString | `IList` de `Point` | |
| Polygon | `IList` de `Ring` | |
| MultiLineString | `IList` de `LineString` | |
| MultiPolygon | `IList` de `Polygon` | |
| Geometry | Cualquier tipo de geometría anterior | Variante de todos los tipos de geometría |
***
#### No admitido para escritura
| Tipo de ClickHouse | Notas |
| ------------------ | ---------------------------------- |
| Dynamic | Lanza `NotImplementedException` |
| AggregateFunction | Lanza `AggregateFunctionException` |
***
### Manejo de tipos anidados
Los tipos anidados de ClickHouse (`Nested(...)`) se pueden leer y escribir usando la semántica de arrays.
```sql theme={null}
CREATE TABLE test.nested (
id UInt32,
params Nested (param_id UInt8, param_val String)
) ENGINE = Memory
```
```csharp theme={null}
var row1 = new object[] { 1, new[] { 1, 2, 3 }, new[] { "v1", "v2", "v3" } };
var row2 = new object[] { 2, new[] { 4, 5, 6 }, new[] { "v4", "v5", "v6" } };
await client.InsertBinaryAsync(
"test.nested",
new[] { "id", "params.param_id", "params.param_val" },
new[] { row1, row2 }
);
```
## Registro y diagnósticos
El cliente .NET de ClickHouse se integra con las abstracciones de `Microsoft.Extensions.Logging` para ofrecer un registro ligero y opcional. Cuando está habilitado, el driver emite mensajes estructurados sobre eventos del ciclo de vida de la conexión, la ejecución de comandos, las operaciones de transporte y las operaciones de inserción masiva. El registro es totalmente opcional: las aplicaciones que no configuran un logger siguen ejecutándose sin sobrecarga adicional.
### Primeros pasos
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Logging;
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Information);
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
#### Uso de appsettings.json
Puede configurar los niveles de registro mediante la configuración estándar de .NET:
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
var configuration = new ConfigurationBuilder()
.SetBasePath(Directory.GetCurrentDirectory())
.AddJsonFile("appsettings.json")
.Build();
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddConsole();
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
#### Uso de la configuración en memoria
También puede configurar en el código la verbosidad del registro por categoría:
```csharp theme={null}
using ClickHouse.Driver;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;
var categoriesConfiguration = new Dictionary
{
{ "LogLevel:Default", "Warning" },
{ "LogLevel:ClickHouse.Driver.Connection", "Information" },
{ "LogLevel:ClickHouse.Driver.Command", "Debug" }
};
var config = new ConfigurationBuilder()
.AddInMemoryCollection(categoriesConfiguration)
.Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConfiguration(config)
.AddSimpleConsole();
});
var settings = new ClickHouseClientSettings("Host=localhost;Port=8123")
{
LoggerFactory = loggerFactory
};
using var client = new ClickHouseClient(settings);
```
### Categorías y emisores
El driver usa categorías específicas para que puedas ajustar con precisión los niveles de registro de cada componente:
| Categoría | Origen | Aspectos destacados |
| ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `ClickHouse.Driver.Connection` | `ClickHouseConnection` | Ciclo de vida de la conexión, selección de la factoría de clientes HTTP, apertura y cierre de conexiones, gestión de sesiones. |
| `ClickHouse.Driver.Command` | `ClickHouseCommand` | Inicio y finalización de la ejecución de consultas, tiempos, ID de consulta, estadísticas del servidor y detalles de errores. |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | Solicitudes HTTP streaming de bajo nivel, indicadores de compresión, códigos de estado de la respuesta y errores de transporte. |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | Inserción binaria, consultas y otras operaciones |
| `ClickHouse.Driver.NetTrace` | `TraceHelper` | Trazado de red, solo cuando el modo de depuración está habilitado |
#### Ejemplo: Cómo diagnosticar problemas de conexión
```json theme={null}
{
"Logging": {
"LogLevel": {
"ClickHouse.Driver.Connection": "Trace",
"ClickHouse.Driver.Transport": "Trace"
}
}
}
```
Esto registrará:
* Selección de la fábrica de clientes HTTP (pool predeterminado frente a conexión única)
* Configuración del controlador HTTP (`SocketsHttpHandler` o `HttpClientHandler`)
* Configuración del pool de conexiones (`MaxConnectionsPerServer`, `PooledConnectionLifetime`, etc.)
* Configuración de timeout (`ConnectTimeout`, `Expect100ContinueTimeout`, etc.)
* Configuración de SSL/TLS
* Eventos de apertura/cierre de conexiones
* Seguimiento del ID de sesión
### Modo de depuración: tracing de red y diagnóstico
Para ayudar a diagnosticar problemas de red, la biblioteca del driver incluye un asistente que habilita el tracing de bajo nivel de los componentes internos de red de .NET. Para habilitarlo, debe pasar una LoggerFactory con el nivel establecido en Trace y establecer EnableDebugMode en true (o habilitarlo manualmente mediante la clase `ClickHouse.Driver.Diagnostic.TraceHelper`). Los eventos se registrarán en la categoría `ClickHouse.Driver.NetTrace`. Advertencia: esto generará logs extremadamente verbosos y afectará al rendimiento. No se recomienda habilitar el modo de depuración en producción.
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // Debe estar en el nivel Trace para ver los eventos de red
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // Habilita el tracing de red de bajo nivel
};
```
## OpenTelemetry
El driver ofrece compatibilidad integrada con el tracing distribuido de OpenTelemetry mediante la API de .NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing). Cuando está habilitado, el driver emite spans para las operaciones de base de datos que pueden exportarse a backends de observabilidad como Jaeger o al propio ClickHouse (mediante el [OpenTelemetry Collector](/es/guides/use-cases/observability/build-your-own/integrating-opentelemetry)).
### Habilitar el tracing
En las aplicaciones ASP.NET Core, agregue el `ActivitySource` del driver de ClickHouse a su configuración de OpenTelemetry:
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // Suscribirse a los spans del driver de ClickHouse
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()); // O bien AddJaegerExporter(), etc.
```
Para aplicaciones de consola, pruebas o configuración manual:
```csharp theme={null}
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName)
.AddConsoleExporter()
.Build();
```
### Atributos del span
Cada span incluye atributos de base de datos estándar de OpenTelemetry, además de estadísticas de consulta específicas de ClickHouse que pueden usarse para depuración.
| Atributo | Descripción |
| ----------------------------- | --------------------------------------------------------- |
| `db.system` | Siempre `"clickhouse"` |
| `db.name` | Nombre de la base de datos |
| `db.user` | Nombre de usuario |
| `db.statement` | Consulta SQL (si está habilitada) |
| `db.clickhouse.read_rows` | Filas leídas por la consulta |
| `db.clickhouse.read_bytes` | Bytes leídos por la consulta |
| `db.clickhouse.written_rows` | Filas escritas por la consulta |
| `db.clickhouse.written_bytes` | Bytes escritos por la consulta |
| `db.clickhouse.elapsed_ns` | Tiempo de ejecución del lado del servidor en nanosegundos |
### Opciones de configuración
Controle el comportamiento del tracing con `ClickHouseDiagnosticsOptions`:
```csharp theme={null}
using ClickHouse.Driver.Diagnostic;
// Incluir sentencias SQL en spans (valor predeterminado: false por seguridad)
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// Truncar sentencias SQL largas (valor predeterminado: 1000 caracteres)
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
Habilitar `IncludeSqlInActivityTags` puede exponer datos confidenciales en las trazas. Úselo con precaución en entornos de producción.
## Configuración de TLS
Al conectarse a ClickHouse a través de HTTPS, puede configurar el comportamiento de TLS/SSL de varias formas.
### Validación personalizada de certificados
Para entornos de producción que requieran una lógica personalizada de validación de certificados, proporcione su propio `HttpClient` con un controlador `ServerCertificateCustomValidationCallback` configurado:
```csharp theme={null}
using System.Net;
using System.Net.Security;
using ClickHouse.Driver;
var handler = new HttpClientHandler
{
// Obligatorio cuando la compresión está activada (valor predeterminado)
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
ServerCertificateCustomValidationCallback = (message, cert, chain, sslPolicyErrors) =>
{
// Ejemplo: Aceptar la huella digital de un certificado concreto
if (cert?.Thumbprint == "YOUR_EXPECTED_THUMBPRINT")
return true;
// Ejemplo: Aceptar certificados de un emisor concreto
if (cert?.Issuer.Contains("YourOrganization") == true)
return true;
// Valor predeterminado: usar la validación estándar
return sslPolicyErrors == SslPolicyErrors.None;
},
};
var httpClient = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(5) };
var settings = new ClickHouseClientSettings
{
Host = "my.clickhouse.server",
Protocol = "https",
HttpClient = httpClient,
};
using var client = new ClickHouseClient(settings);
```
Consideraciones importantes al proporcionar un `HttpClient` personalizado
* **Descompresión automática**: Debes habilitar `AutomaticDecompression` si la compresión no está desactivada (la compresión está activada de forma predeterminada).
* **Tiempo de espera de inactividad**: Configura `PooledConnectionIdleTimeout` con un valor inferior al `keep_alive_timeout` del servidor (10 segundos en ClickHouse Cloud) para evitar errores de conexión causados por conexiones semiabiertas.
## Compatibilidad con los ORM
Los ORM requieren la API de ADO.NET (`ClickHouseConnection`). Para gestionar correctamente el ciclo de vida de la conexión, cree las conexiones desde un `ClickHouseDataSource`:
```csharp theme={null}
// Registrar DataSource como singleton
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default");
// Crear conexiones para usarlas con el ORM
await using var connection = await dataSource.OpenConnectionAsync();
// Pasar la conexión al ORM...
```
### Dapper
`ClickHouse.Driver` funciona con Dapper. El driver convierte automáticamente la sintaxis `@parameter` de Dapper a la sintaxis nativa `{parameter:Type}` de ClickHouse, e infiere los tipos a partir de los valores de .NET.
Usa `ClickHouseDataSource` para gestionar correctamente el ciclo de vida de la conexión:
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // Registrar como singleton en la DI
using var connection = dataSource.CreateConnection();
```
#### Estilos para pasar parámetros
Se admiten todos los estilos estándar de parámetros de Dapper:
**Objetos anónimos:**
```csharp theme={null}
await connection.ExecuteAsync(
"INSERT INTO users (id, name, balance) VALUES (@Id, @Name, @Balance)",
new { Id = 1, Name = "alice", Balance = 3.14 });
```
**Clases POCO:**
```csharp theme={null}
class InsertParams
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
var param = new InsertParams { Id = 42, Name = "bob", Balance = 99.9 };
await connection.ExecuteAsync(
"INSERT INTO users (id, name, balance) VALUES (@Id, @Name, @Balance)", param);
```
**Diccionario:**
```csharp theme={null}
var parameters = new Dictionary { { "Id", 2 } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", parameters);
```
**`DynamicParameters` (de un diccionario o de un objeto anónimo):**
```csharp theme={null}
var dynParams = new DynamicParameters(new { Id = 1 });
// o bien: new DynamicParameters(new Dictionary { { "Id", 1 } });
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", dynParams);
```
#### Consultas con POCOs
Dapper asigna columnas a propiedades por nombre (sin distinguir entre mayúsculas y minúsculas):
```csharp theme={null}
class User
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
// De una tabla
var users = (await connection.QueryAsync("SELECT id, name, balance FROM users")).ToList();
// De un literal
var row = (await connection.QueryAsync("SELECT 1 as id, 'hello' as name, 2.5 as balance")).Single();
```
#### Sintaxis de parámetros nativa de ClickHouse
Cuando necesites un control explícito de los tipos, usa directamente en el SQL la sintaxis `{param:Type}` de ClickHouse con un `Dictionary` para los valores de los parámetros. No combines la sintaxis `@param` con la sintaxis `{param:Type}` para el mismo parámetro.
```csharp theme={null}
var parameters = new Dictionary { { "value", 42 } };
var result = await connection.QueryAsync("SELECT {value:Int32}", parameters);
```
#### WHERE IN
**La expansión nativa de IN de Dapper funciona:**
```csharp theme={null}
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id IN @Ids ORDER BY id",
new { Ids = new[] { 1, 3, 5 } });
```
Dapper reescribe esto como `WHERE id IN (@Ids1, @Ids2, @Ids3)`, y el driver convierte cada parámetro expandido.
**La función `has()` de ClickHouse con un parámetro Array también funciona:**
```csharp theme={null}
var parameters = new Dictionary { { "ids", new[] { 1, 3, 5 } } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE has({ids:Array(Int32)}, id) ORDER BY id",
parameters);
```
#### Manejadores de tipos personalizados
Algunos tipos de ClickHouse, p. ej., `ITuple`, `BigInteger` y `ClickHouseDecimal`, requieren registrar manejadores al inicio:
```csharp theme={null}
// ClickHouseDecimal (para columnas Decimal64/128/256)
SqlMapper.AddTypeHandler(new ClickHouseDecimalHandler());
// BigInteger (para columnas Int128/Int256/UInt128/UInt256)
SqlMapper.AddTypeHandler(new BigIntegerHandler());
// IPAddress (para columnas IPv4/IPv6)
SqlMapper.AddTypeHandler(new IpAddressHandler());
```
Consulte el [ejemplo de Dapper](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/ORM/ORM_001_Dapper.cs) como ejemplo de implementación de un manejador de tipos.
#### Dapper.Contrib
`GetAll()` y `Get(id)` funcionan. `Insert()` no: genera sintaxis de SQL Server (`SCOPE_IDENTITY`, `[]`). En su lugar, se recomienda usar el método nativo `InsertBinaryAsync` de `ClickHouseClient`.
```csharp theme={null}
[Table("test.users")]
record class UserRecord(int Id, string Name, DateTime Timestamp);
var all = await connection.GetAllAsync();
var one = await connection.GetAsync(1);
```
Los nombres de las propiedades deben coincidir exactamente con los nombres de columna de ClickHouse (la coincidencia es sensible a mayúsculas y minúsculas).
#### Limitaciones
| Qué | Estado | Detalles |
| ----------------------------- | ------------- | -------------------------------------------------------------------------- |
| Tuple como **resultado** | Funciona | Requiere registrar `SqlMapper.TypeHandler` |
| Tuple como **parámetro** | No compatible | Dapper no puede serializar `ITuple`/`Tuple<>` como valor de `DbParameter` |
| Tipos anidados como parámetro | No compatible | Mismo motivo: Dapper rechaza los tipos complejos como valores de parámetro |
| Tipos Geo como parámetro | No compatible | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | No compatible | Genera sintaxis específica de SQL Server |
| Tipo `Nothing` | No compatible | No tiene una representación significativa en .NET |
### Linq2db
Este driver es compatible con [linq2db](https://github.com/linq2db/linq2db), un ORM ligero y un proveedor de LINQ para .NET. Consulta el sitio web del proyecto para obtener documentación detallada.
**Ejemplo de uso:**
Crea una `DataConnection` con el proveedor de ClickHouse:
```csharp theme={null}
using LinqToDB;
using LinqToDB.Data;
using LinqToDB.DataProvider.ClickHouse;
var connectionString = "Host=localhost;Port=8123;Database=default";
var options = new DataOptions()
.UseClickHouse(connectionString, ClickHouseProvider.ClickHouseDriver);
await using var db = new DataConnection(options);
```
Los mapeos de tablas pueden definirse mediante atributos o la API fluida. Si los nombres de la clase y de las propiedades coinciden exactamente con los nombres de la tabla y de las columnas, no se necesita ninguna configuración:
```csharp theme={null}
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
```
**Consultas:**
```csharp theme={null}
await using var db = new DataConnection(options);
var products = await db.GetTable()
.Where(p => p.Price > 100)
.OrderByDescending(p => p.Name)
.ToListAsync();
```
**Copia masiva:**
Utilice `BulkCopyAsync` para realizar inserciones masivas de forma eficiente.
```csharp theme={null}
await using var db = new DataConnection(options);
var table = db.GetTable();
var options = new BulkCopyOptions
{
MaxBatchSize = 100000,
MaxDegreeOfParallelism = 1,
WithoutSession = true
};
await table.BulkCopyAsync(options, products);
```
### Entity Framework Core
El proveedor oficial de Entity Framework Core para ClickHouse. Permite asignar clases de C# a tablas de ClickHouse, realizar consultas con LINQ e insertar datos mediante `SaveChanges`, todo ello con los patrones habituales de EF Core.
* **NuGet**: [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **Código fuente**: [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
Este proveedor está en desarrollo activo. La versión actual admite consultas LINQ (incluidos JOIN, subconsultas y operaciones de conjuntos), `INSERT` mediante `SaveChanges` / `BulkInsertAsync`, migraciones con DDL completo (CREATE / ALTER / DROP) y la configuración del motor de tabla específica de ClickHouse. `UPDATE` / `DELETE` no son compatibles.
#### Instalación
```bash theme={null}
dotnet add package ClickHouse.EntityFrameworkCore
```
Requiere .NET 10.0 y EF Core 10.
#### Inicio rápido
Define la entidad y `DbContext`, y luego haz consultas con LINQ:
```csharp theme={null}
using Microsoft.EntityFrameworkCore;
public class PageView
{
public long Id { get; set; }
public string Path { get; set; }
public DateOnly Date { get; set; }
public string UserAgent { get; set; }
}
public class AnalyticsContext : DbContext
{
public DbSet PageViews { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
=> optionsBuilder.UseClickHouse("Host=localhost;Database=analytics");
}
// Consulta
await using var ctx = new AnalyticsContext();
var topPages = await ctx.PageViews
.Where(v => v.Date >= new DateOnly(2024, 1, 1))
.GroupBy(v => v.Path)
.Select(g => new { Path = g.Key, Views = g.Count() })
.OrderByDescending(x => x.Views)
.Take(10)
.ToListAsync();
```
#### Tipos compatibles
| Categoría | Tipos de ClickHouse | Tipos de CLR |
| ------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Enteros** | `Int8`–`Int64`, `UInt8`–`UInt64` | `sbyte`, `short`, `int`, `long`, `byte`, `ushort`, `uint`, `ulong` |
| **Enteros grandes** | `Int128`, `Int256`, `UInt128`, `UInt256` | `BigInteger` |
| **Punto flotante** | `Float32`, `Float64`, `BFloat16` | `float`, `double` |
| **Decimales** | `Decimal(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` o `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **Cadenas** | `String`, `FixedString(N)` | `string` |
| **Enumeraciones** | `Enum8(...)`, `Enum16(...)` | `string` o `enum` de C# |
| **Fecha/hora** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **Hora** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **Red** | `IPv4`, `IPv6` | `IPAddress` |
| **Arrays** | `Array(T)` | `T[]`, `List`, `IList`, `ICollection`, `IReadOnlyList`, `IReadOnlyCollection`, `IEnumerable` |
| **Mapas** | `Map(K, V)` | `Dictionary` |
| **Tuples** | `Tuple(T1, ...)` | `Tuple<...>` o `ValueTuple<...>` |
| **Variant** | `Variant(T1, T2, ...)` | `object` |
| **Dinámico** | `Dynamic` | `object` |
| **JSON** | `Json` | `JsonNode` o `string` |
| **Geográficos** | `Point`, `Ring`, `LineString`, `Polygon`, `MultiLineString`, `MultiPolygon`, `Geometry` | `Tuple` y arrays de estos; `object` para `Geometry` |
| **Envoltorios** | `Nullable(T)`, `LowCardinality(T)` | Se desempaquetan automáticamente |
Usa `ClickHouseDecimal` (de `ClickHouse.Driver.Numerics`) en lugar de `decimal` cuando necesites toda la precisión de las columnas `Decimal128`/`Decimal256`: `decimal` de .NET está limitado a 28–29 dígitos significativos.
#### Operaciones LINQ compatibles
**Consultas:** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY y agregaciones:** `GroupBy` con `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` — incluido `HAVING` (`.Where()` después de `.GroupBy()`), varias agregaciones en una sola proyección y `OrderBy` sobre resultados agregados.
**JOINs:** `Join` (INNER) y patrones `GroupJoin`/`SelectMany` (LEFT y CROSS). LEFT JOIN devuelve `null` real para las filas sin coincidencia (consulta [la semántica de null de LEFT JOIN](#ef-core-join-nulls) más abajo).
**Subconsultas:** `Contains` / `IN` correlacionados, `Any` / `EXISTS`, `All` y subconsultas escalares en proyecciones.
**Operaciones de conjuntos:** `Concat` (→ `UNION ALL`), `Union` (→ `UNION DISTINCT`), `Intersect`, `Except`.
**Colecciones locales insertadas en línea:** los joins y `Contains` con colecciones en memoria (`int[]`, `List`, etc.) se traducen en una serie de `UNION`.
**Métodos de cadena:** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (y el operador `+`).
**Funciones matemáticas:** los métodos estándar de `Math` y `MathF` se traducen a sus equivalentes en ClickHouse — funciones aritméticas, logarítmicas, trigonométricas y auxiliares.
##### Semántica de NULL en LEFT JOIN
El proveedor inserta automáticamente `set_join_use_nulls=1` en cada connection path para ajustarse a las expectativas de Entity Framework sobre el comportamiento de JOIN.
Si su servidor ClickHouse o profile impide cambiar esta configuración (por ejemplo, un profile `readonly=1`), desactívelo con:
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
Con la exclusión activada, LEFT JOIN devuelve los valores predeterminados de las columnas de ClickHouse y la detección de navegación de EF basada en valores nulos deja de funcionar como se espera. Use comparaciones explícitas con `0` / `""` en lugar de `== null`.
#### Inserción de datos
`SaveChanges` usa la API nativa `InsertBinaryAsync` del driver: codificación RowBinary con compresión GZip, mucho más eficiente que SQL con parámetros:
```csharp theme={null}
await using var ctx = new AnalyticsContext();
ctx.PageViews.Add(new PageView
{
Id = 1,
Path = "/home",
Date = new DateOnly(2024, 6, 15),
UserAgent = "Mozilla/5.0"
});
await ctx.SaveChangesAsync();
```
Las entidades pasan de `Added` a `Unchanged` tras guardar, igual que con cualquier otro proveedor de EF Core.
**El tamaño del lote** es configurable (valor predeterminado: 1000):
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### Inserción masiva
Para cargas de alto rendimiento, use `BulkInsertAsync` en lugar de `SaveChanges`. Es un método de extensión de `DbContext` que omite por completo el seguimiento de cambios, la resolución de identidad y la administración del estado de EF Core; llama directamente al método `InsertBinaryAsync` del driver con codificación RowBinary y compresión GZip.
Esto lo hace adecuado para cargar grandes volúmenes de datos cuando no necesita el seguimiento de entidades después de la inserción:
```csharp theme={null}
var events = Enumerable.Range(0, 100_000)
.Select(i => new PageView
{
Id = i,
Path = $"/page/{i}",
Date = DateOnly.FromDateTime(DateTime.Today)
});
long rowsInserted = await ctx.BulkInsertAsync(events);
```
La entrada puede ser cualquier `IEnumerable` — recorre las entidades en streaming sin cargarlas todas en memoria. El valor devuelto es el número de filas insertadas. Las entidades **no** se adjuntan al `DbContext` después de la inserción, por lo que no hay transición de estado `Added` → `Unchanged`.
#### Enumeraciones
Las columnas `Enum8`/`Enum16` de ClickHouse se pueden asignar a propiedades `string` o a tipos `enum` de C#. Al usar enumeraciones de C#, el proveedor convierte automáticamente entre la enumeración y su representación textual:
```csharp theme={null}
public enum Status { Active, Inactive, Pending }
public class User
{
public long Id { get; set; }
public Status Status { get; set; }
}
// Consulta con valores de enum
var active = await ctx.Users
.Where(u => u.Status == Status.Active)
.ToListAsync();
```
#### Conversiones de tipos personalizadas
El sistema `ValueConverter` de EF Core te permite mapear tipos personalizados a tipos que el proveedor ya admite. El proveedor nunca ve tu tipo personalizado: EF Core realiza la conversión en ese punto.
**Conversión por propiedad:**
```csharp theme={null}
public class Money
{
public decimal Amount { get; set; }
public string Currency { get; set; }
}
public class Order
{
public long Id { get; set; }
public Money Price { get; set; }
}
// En el método OnModelCreating:
modelBuilder.Entity()
.Property(o => o.Price)
.HasConversion(
m => $"{m.Amount}|{m.Currency}",
s => new Money
{
Amount = decimal.Parse(s.Split('|')[0]),
Currency = s.Split('|')[1]
})
.HasColumnType("String");
```
**Clase de convertidor reutilizable:**
```csharp theme={null}
public class MoneyConverter : ValueConverter
{
public MoneyConverter() : base(
m => $"{m.Amount}|{m.Currency}",
s => Parse(s)) { }
private static Money Parse(string s)
{
var parts = s.Split('|');
return new Money { Amount = decimal.Parse(parts[0]), Currency = parts[1] };
}
}
// Aplicar a una propiedad individual:
.HasConversion()
// O aplicarlo a todas las propiedades de un tipo mediante convenciones:
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
configurationBuilder.Properties()
.HaveConversion();
}
```
#### Anotaciones de tipo de columna
Para tipos escalares como `string`, `int`, `DateTime`, etc., el proveedor infiere automáticamente el tipo de ClickHouse. Para los tipos parametrizados y los envoltorios, debe especificar explícitamente el tipo de ClickHouse.
**Uso de anotaciones de datos (atributos):**
```csharp theme={null}
using System.ComponentModel.DataAnnotations.Schema;
using Microsoft.EntityFrameworkCore;
[Table("sensor_readings")]
public class SensorReading
{
public long Id { get; set; }
[Column(TypeName = "Array(String)")]
public string[] Tags { get; set; }
[Column(TypeName = "Map(String, String)")]
public Dictionary Metadata { get; set; }
[Column(TypeName = "Nullable(Float64)")]
public double? Value { get; set; }
[Column(TypeName = "Decimal128(18)")]
public decimal HighPrecision { get; set; }
}
```
**Uso de la API fluida en `OnModelCreating`:**
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("sensor_readings");
e.Property(x => x.Tags).HasColumnType("Array(String)");
e.Property(x => x.Metadata).HasColumnType("Map(String, String)");
e.Property(x => x.Value).HasColumnType("Nullable(Float64)");
e.Property(x => x.Category).HasColumnType("LowCardinality(String)");
e.Property(x => x.HighPrecision).HasColumnType("Decimal128(18)");
});
```
Se admiten envoltorios anidados como `Array(Nullable(Int32))` y `LowCardinality(Nullable(String))` — el proveedor elimina automáticamente `Nullable` y `LowCardinality` en cada nivel de anidamiento.
#### Columnas Variant y Dynamic
Las columnas `Variant(T1, T2, ...)` y `Dynamic` de ClickHouse se corresponden con `object` en .NET. Como `object` es demasiado genérico para la inferencia automática de tipos, debe declarar explícitamente el tipo de almacenamiento mediante `.HasColumnType()`:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public object? Payload { get; set; }
}
// En OnModelCreating:
entity.Property(e => e.Payload).HasColumnType("Variant(String, UInt64, Array(UInt64))");
// o bien:
entity.Property(e => e.Payload).HasColumnType("Dynamic");
```
Al leer, el valor se deserializa automáticamente al tipo .NET correspondiente según el discriminador almacenado (p. ej., `string`, `ulong`, `ulong[]`).
#### Columnas JSON
El proveedor admite el tipo de columna `Json` de ClickHouse, que se corresponde con `System.Text.Json.Nodes.JsonNode` (principal) o `string` (mediante `ValueConverter` automático):
```csharp theme={null}
using System.Text.Json.Nodes;
public class Event
{
public long Id { get; set; }
public JsonNode? Data { get; set; }
}
// En OnModelCreating:
entity.Property(e => e.Data).HasColumnType("Json");
```
La lectura y escritura de JSON funcionan tanto con `SaveChanges` como con `BulkInsertAsync`:
```csharp theme={null}
ctx.Events.Add(new Event
{
Id = 1,
Data = JsonNode.Parse("""{"action": "click", "x": 100, "y": 200}""")
});
await ctx.SaveChangesAsync();
var ev = await ctx.Events.Where(e => e.Id == 1).SingleAsync();
string action = ev.Data!["action"]!.GetValue(); // "click"
```
Si prefiere cadenas JSON sin procesar, asigne a la propiedad el tipo `string` con un tipo de columna `Json`; el proveedor aplica automáticamente un `ValueConverter`:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public string? Data { get; set; } // cadena JSON sin procesar
}
entity.Property(e => e.Data).HasColumnType("Json");
```
* **Sin traducción de rutas JSON** — `entity.Data["name"]` en LINQ no se corresponde con la sintaxis SQL `data.name` de ClickHouse. Filtre por columnas no JSON e inspeccione el JSON en memoria.
* **Semántica de NULL** — El tipo JSON de ClickHouse devuelve `{}` (objeto vacío) para los valores NULL en lugar de SQL NULL.
* **Precisión de enteros** — El JSON de ClickHouse almacena todos los enteros como `Int64`. Al leerlo mediante `JsonNode`, use `GetValue()` en lugar de `GetValue()`.
#### Motores de tablas
Configure los motores de tablas de ClickHouse y las cláusulas específicas de cada motor mediante la API fluida `ToTable(name, t => ...)`. Si no se configura ningún motor, el proveedor usa `MergeTree` de forma predeterminada, con `ORDER BY` derivado de la clave primaria de la entidad.
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("events", t => t
.HasMergeTreeEngine()
.WithOrderBy("UserId", "Timestamp")
.WithPartitionBy("toYYYYMM(Timestamp)")
.WithPrimaryKey("UserId")
.WithSettings("index_granularity = 8192"));
});
```
Familias de motores compatibles:
| Engine | Método fluido | Notas |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `MergeTree` | `HasMergeTreeEngine()` | Predeterminado si no se configura ninguno |
| `ReplacingMergeTree` | `HasReplacingMergeTreeEngine("Version", "IsDeleted")` o `HasReplacingMergeTreeEngine(e => e.Version)` | Las columnas Version / IsDeleted son opcionales |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` o `HasSummingMergeTreeEngine(e => new { … })` | Columnas a sumar opcionales |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` o `HasCollapsingMergeTreeEngine(e => e.Sign)` | La columna `Sign` debe ser `Int8` |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` o `(e => e.Sign, e => e.Version)` | — |
| `GraphiteMergeTree` | `HasGraphiteMergeTreeEngine("config_section")` | — |
| `Log`, `TinyLog`, `StripeLog`, `Memory` | `HasLogEngine()`, `HasTinyLogEngine()`, `HasStripeLogEngine()`, `HasMemoryEngine()` | Sin ORDER BY / PARTITION BY |
**Cláusulas del motor:** `WithOrderBy`, `WithPartitionBy`, `WithPrimaryKey`, `WithSampleBy`, `WithTtl`, `WithSettings`. Todas se aplican al generador de motores devuelto por `HasXxxEngine()`.
**Características a nivel de columna:** `HasCodec`, `HasTtl`, `HasComment`, `HasDefault` — todas forman parte de las migraciones.
**Índices de omisión de datos** — mediante `HasIndex(...).HasSkippingIndexType(...)`:
```csharp theme={null}
modelBuilder.Entity()
.HasIndex(e => e.UserId)
.HasSkippingIndexType("minmax")
.HasGranularity(4);
// Índice con parámetros (p. ej., bloom_filter, tokenbf_v1):
modelBuilder.Entity()
.HasIndex(e => e.Tag)
.HasSkippingIndexType("bloom_filter")
.HasSkippingIndexParams("0.01")
.HasGranularity(1);
```
Los índices estándar (sin omitir datos) se ignoran sin avisar, ya que ClickHouse no tiene ningún equivalente. Los índices únicos provocan un error, ya que ClickHouse no garantiza la unicidad.
#### Migraciones
Flujo de trabajo estándar para las migraciones de EF Core:
```bash theme={null}
dotnet ef migrations add InitialCreate
dotnet ef database update
```
Operaciones admitidas:
| Operación | Genera |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `CREATE TABLE` | Incluye la cláusula ENGINE, ORDER BY, PARTITION BY, SETTINGS, códecs/TTL/comentarios/valores predeterminados de columnas |
| `ALTER TABLE ADD COLUMN` | — |
| `ALTER TABLE DROP COLUMN` | — |
| `ALTER TABLE MODIFY COLUMN` | Gestiona el cambio de tipo, además de la adición/eliminación de anotaciones (CODEC, TTL, COMMENT, DEFAULT) |
| `ALTER TABLE RENAME COLUMN` | — |
| `RENAME TABLE` | — |
| `ALTER TABLE ADD INDEX` / `DROP INDEX` | Solo índices de omisión de datos |
| `CREATE DATABASE` / `DROP DATABASE` | Mediante `EnsureCreated` / `EnsureDeleted` y migraciones |
#### Limitaciones de las migraciones
| Funcionalidad | Motivo |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claves foráneas | ClickHouse no hace cumplir las claves foráneas. Las migraciones rechazan `AddForeignKey`; el validador del modelo emite una advertencia al compilar el modelo. |
| Restricciones de unicidad / índices únicos | ClickHouse no hace cumplir la unicidad. Los índices únicos generan un error durante la migración. |
| Valores generados por el servidor (incremento automático / `IDENTITY`) | ClickHouse no tiene un equivalente. |
| columnas `Nested(…)` | Aún no son compatibles como tipo CLR asignado. |
| Entidades owned como JSON (`.ToJson()`) | La correspondencia estructural de JSON para entidades owned aún no está implementada. Use `JsonNode` / `string` en una columna `Json` en su lugar (consulte [columnas JSON](#ef-core-json)). |
Además de las migraciones, el proveedor tampoco admite aún:
* **`UPDATE` / `DELETE`**
* **Transacciones**: `BeginTransaction` es una operación sin efecto. ClickHouse no admite transacciones ACID.
* **Traducción de consultas con rutas JSON**: `entity.Data["key"]` en LINQ no se traduce a la sintaxis SQL `data.key` de ClickHouse. Filtre por columnas que no sean JSON e inspeccione el JSON en memoria.
## Limitaciones
### Columnas de AggregateFunction
Las columnas de tipo `AggregateFunction(...)` no se pueden consultar ni insertar directamente.
Para insertar:
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
Para consultar:
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***