()` antes da serialização. Tentar serializar um tipo não registrado lança `ClickHouseJsonSerializationException`.
* Propriedades de Dicionário e array/lista exigem dicas de tipo na definição da coluna para serem serializadas corretamente. Sem essas dicas, use o modo String.
* Valores nulos em propriedades POCO só são gravados quando o caminho tem uma dica de tipo `Nullable(T)` na definição da coluna. O ClickHouse não permite tipos `Nullable` em caminhos JSON dinâmicos, portanto propriedades nulas sem dica são ignoradas.
* Os atributos `ClickHouseJsonPath` e `ClickHouseJsonIgnore` são ignorados no modo String (eles só funcionam no modo Binary).
***
#### Outros tipos
| ClickHouse Type | Accepted .NET Types | Notas |
| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| UUID | `Guid`, `string` | `string` é analisada como `Guid` |
| IPv4 | `IPAddress`, `string` | Deve ser IPv4; `string` é analisada via `IPAddress.Parse()` |
| IPv6 | `IPAddress`, `string` | Deve ser IPv6; `string` é analisada via `IPAddress.Parse()` |
| Nothing | Qualquer | Não grava nada (no-op) |
| Dynamic | — | **Sem suporte** (lança `NotImplementedException`) |
| Array(T) | `IList`, `null` | `null` grava um array vazio |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | A quantidade de elementos deve corresponder à aridade da tupla |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull`, ou tipos aceitos por T | Grava o byte indicador de null antes do valor |
| Enum8 | `string`, `sbyte`, tipos numéricos | `string` é procurada no dicionário do enum |
| Enum16 | `string`, `short`, tipos numéricos | `string` é procurada no dicionário do enum |
| LowCardinality(T) | Tipos aceitos por T | Delega ao tipo subjacente |
| SimpleAggregateFunction | Tipos aceitos pelo tipo subjacente | Delega ao tipo subjacente |
| Nested(...) | `IList` de tuplas | A quantidade de elementos deve corresponder à quantidade de campos |
| Variant(T1, T2, ...) | Valor correspondente a um de T1, T2, ... | Lança `ArgumentException` se não houver correspondência de tipo |
| QBit(T, dim) | `IList` | Delega a Array; a dimensão é apenas metadado |
***
#### Tipos de geometria
| Tipo do ClickHouse | Tipos .NET aceitos | Observações |
| ------------------ | ------------------------------------------------------- | -------------------------------------- |
| 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 | Qualquer tipo de geometria acima | Variant de todos os tipos de geometria |
***
#### Não suportado para escrita
| Tipo do ClickHouse | Notas |
| ------------------ | ---------------------------------- |
| Dynamic | Lança `NotImplementedException` |
| AggregateFunction | Lança `AggregateFunctionException` |
***
### Tratamento do tipo Nested
Os tipos aninhados do ClickHouse (`Nested(...)`) podem ser lidos e gravados usando 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 }
);
```
## Logging e diagnósticos
O cliente .NET do ClickHouse se integra às abstrações `Microsoft.Extensions.Logging` para oferecer logging leve e opcional. Quando habilitado, o driver emite mensagens estruturadas para eventos do ciclo de vida da conexão, execução de comandos, operações de transporte e operações de inserção em massa. O logging é totalmente opcional — aplicações que não configuram um logger continuam em execução sem sobrecarga adicional.
### Início rápido
```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);
```
#### Usando appsettings.json
Você pode configurar os níveis de log usando a configuração padrão do .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);
```
#### Usando configuração em memória
Você também pode configurar o nível de verbosidade do logging por categoria no código:
```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);
```
### Categorias e emissores
O driver usa categorias específicas para que você possa ajustar com precisão os níveis de log por componente:
| Categoria | Origem | Destaques |
| ------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `ClickHouse.Driver.Connection` | `ClickHouseConnection` | Ciclo de vida da conexão, seleção da fábrica de clientes HTTP, abertura/fechamento de conexão e gerenciamento de sessão. |
| `ClickHouse.Driver.Command` | `ClickHouseCommand` | Início/conclusão da execução da consulta, temporização, IDs de consulta, estatísticas do servidor e detalhes de erro. |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | Requisições HTTP streaming de baixo nível, sinalizadores de compressão, códigos de status da resposta e falhas de transporte. |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | Insert binário, consultas e outras operações |
| `ClickHouse.Driver.NetTrace` | `TraceHelper` | Rastreamento de rede, somente quando o modo de depuração está habilitado |
#### Exemplo: Diagnóstico de problemas de conexão
```json theme={null}
{
"Logging": {
"LogLevel": {
"ClickHouse.Driver.Connection": "Trace",
"ClickHouse.Driver.Transport": "Trace"
}
}
}
```
Isso registrará:
* Seleção da fábrica do cliente HTTP (pool padrão vs. conexão única)
* Configuração do handler HTTP (SocketsHttpHandler ou HttpClientHandler)
* Configurações do pool de conexões (MaxConnectionsPerServer, PooledConnectionLifetime etc.)
* Configurações de timeout (ConnectTimeout, Expect100ContinueTimeout etc.)
* Configuração de SSL/TLS
* Eventos de abertura/fechamento de conexões
* Rastreamento do ID da sessão
### Modo de depuração: rastreamento de rede e diagnósticos
Para ajudar a diagnosticar problemas de rede, a biblioteca do driver inclui um auxiliar que habilita o rastreamento de baixo nível dos componentes internos de rede do .NET. Para habilitá-lo, você deve passar uma LoggerFactory com o nível definido como Trace e definir EnableDebugMode como true (ou habilitá-lo manualmente pela classe `ClickHouse.Driver.Diagnostic.TraceHelper`). Os eventos serão registrados na categoria `ClickHouse.Driver.NetTrace`. Aviso: isso gerará logs extremamente detalhados e afetará o desempenho. Não é recomendável habilitar o modo de depuração em production.
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // Deve estar no nível Trace para exibir eventos de rede
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // Habilita o rastreamento de rede de baixo nível
};
```
## OpenTelemetry
O driver oferece suporte nativo ao rastreamento distribuído com OpenTelemetry por meio da API .NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing). Quando habilitado, o driver emite spans para operações de banco de dados que podem ser exportados para backends de observabilidade, como Jaeger ou o próprio ClickHouse (por meio do [OpenTelemetry Collector](/pt-BR/guides/use-cases/observability/build-your-own/integrating-opentelemetry)).
### Habilitando o rastreamento
Em aplicações ASP.NET Core, adicione o `ActivitySource` do driver do ClickHouse à configuração do OpenTelemetry:
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // Assina os spans do driver ClickHouse
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()); // Ou AddJaegerExporter(), etc.
```
Para aplicativos de console, testes ou configuração manual:
```csharp theme={null}
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName)
.AddConsoleExporter()
.Build();
```
### Atributos de span
Cada span inclui atributos de banco de dados padrão do OpenTelemetry, além de estatísticas de consulta específicas do ClickHouse que podem ser usadas para depuração.
| Atributo | Descrição |
| ----------------------------- | ---------------------------------------------- |
| `db.system` | Sempre `"clickhouse"` |
| `db.name` | Nome do banco de dados |
| `db.user` | Nome de usuário |
| `db.statement` | Consulta SQL (se estiver habilitada) |
| `db.clickhouse.read_rows` | Linhas lidas pela consulta |
| `db.clickhouse.read_bytes` | Bytes lidos pela consulta |
| `db.clickhouse.written_rows` | Linhas gravadas pela consulta |
| `db.clickhouse.written_bytes` | Bytes gravados pela consulta |
| `db.clickhouse.elapsed_ns` | Tempo de execução no servidor em nanossegundos |
### Opções de configuração
Controle o comportamento do rastreamento por meio de `ClickHouseDiagnosticsOptions`:
```csharp theme={null}
using ClickHouse.Driver.Diagnostic;
// Incluir instruções SQL nos spans (padrão: false por segurança)
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// Truncar instruções SQL longas (padrão: 1000 caracteres)
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
Ativar `IncludeSqlInActivityTags` pode expor dados sensíveis nos seus traces. Use com cautela em ambientes de produção.
## Configuração de TLS
Ao se conectar ao ClickHouse via HTTPS, você pode configurar o comportamento do TLS/SSL de várias formas.
### Validação personalizada de certificados
Para ambientes de produção que exigem uma lógica personalizada de validação de certificados, forneça seu próprio `HttpClient` com um handler `ServerCertificateCustomValidationCallback` configurado:
```csharp theme={null}
using System.Net;
using System.Net.Security;
using ClickHouse.Driver;
var handler = new HttpClientHandler
{
// Obrigatório quando a compactação está ativada (padrão)
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
ServerCertificateCustomValidationCallback = (message, cert, chain, sslPolicyErrors) =>
{
// Exemplo: Aceitar a impressão digital de um certificado específico
if (cert?.Thumbprint == "YOUR_EXPECTED_THUMBPRINT")
return true;
// Exemplo: Aceitar certificados de um emissor específico
if (cert?.Issuer.Contains("YourOrganization") == true)
return true;
// Padrão: usar a validação padrão
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);
```
Considerações importantes ao fornecer um HttpClient personalizado
* **Descompressão automática**: Você deve habilitar `AutomaticDecompression` se a compressão não estiver desabilitada (a compressão é habilitada por padrão).
* **Tempo limite de inatividade**: Defina `PooledConnectionIdleTimeout` com um valor menor que o `keep_alive_timeout` do servidor (10 segundos para ClickHouse Cloud) para evitar erros de conexão causados por conexões semiabertas.
## Suporte a ORMs
ORMs exigem a API ADO.NET (`ClickHouseConnection`). Para gerenciar corretamente o ciclo de vida da conexão, crie as conexões a partir de um `ClickHouseDataSource`:
```csharp theme={null}
// Registre o DataSource como singleton
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default");
// Crie conexões para uso pelo ORM
await using var connection = await dataSource.OpenConnectionAsync();
// Passe a conexão para o seu ORM...
```
### Dapper
`ClickHouse.Driver` funciona com Dapper. O driver converte automaticamente a sintaxe `@parameter` do Dapper para a sintaxe nativa `{parameter:Type}` do ClickHouse, com os tipos inferidos a partir dos valores do .NET.
Use `ClickHouseDataSource` para gerenciar corretamente o ciclo de vida da conexão:
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // Registrar como singleton na injeção de dependência
using var connection = dataSource.CreateConnection();
```
#### Estilos de passagem de parâmetros
Todos os estilos padrão de passagem de parâmetros do Dapper são compatíveis:
**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 });
```
**Classes do tipo 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);
```
**Dicionário:**
```csharp theme={null}
var parameters = new Dictionary { { "Id", 2 } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", parameters);
```
**`DynamicParameters` (a partir de um dicionário ou de um objeto anônimo):**
```csharp theme={null}
var dynParams = new DynamicParameters(new { Id = 1 });
// ou: new DynamicParameters(new Dictionary { { "Id", 1 } });
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", dynParams);
```
#### Consultas com POCOs
O Dapper mapeia colunas para propriedades pelo nome (sem diferenciar maiúsculas de minúsculas):
```csharp theme={null}
class User
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
// A partir de uma tabela
var users = (await connection.QueryAsync("SELECT id, name, balance FROM users")).ToList();
// A partir de um literal
var row = (await connection.QueryAsync("SELECT 1 as id, 'hello' as name, 2.5 as balance")).Single();
```
#### Sintaxe nativa de parâmetros do ClickHouse
Quando precisar de controle explícito sobre o tipo, use diretamente no SQL a sintaxe `{param:Type}` do ClickHouse com um `Dictionary` para os valores dos parâmetros. Não combine a sintaxe `@param` com a sintaxe `{param:Type}` para o mesmo parâmetro.
```csharp theme={null}
var parameters = new Dictionary { { "value", 42 } };
var result = await connection.QueryAsync("SELECT {value:Int32}", parameters);
```
#### WHERE IN
**A expansão nativa do IN no 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 } });
```
O Dapper reescreve isso como `WHERE id IN (@Ids1, @Ids2, @Ids3)`, e o driver converte cada parâmetro expandido.
**O `has()` do ClickHouse com parâmetro Array também 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);
```
#### Manipuladores de tipo personalizados
Alguns tipos do ClickHouse, como `ITuple`, `BigInteger` e `ClickHouseDecimal`, precisam ter manipuladores registrados na inicialização:
```csharp theme={null}
// ClickHouseDecimal (para as colunas Decimal64/128/256)
SqlMapper.AddTypeHandler(new ClickHouseDecimalHandler());
// BigInteger (para as colunas Int128/Int256/UInt128/UInt256)
SqlMapper.AddTypeHandler(new BigIntegerHandler());
// IPAddress (para as colunas IPv4/IPv6)
SqlMapper.AddTypeHandler(new IpAddressHandler());
```
Consulte o [exemplo do Dapper](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/ORM/ORM_001_Dapper.cs) para ver uma implementação de exemplo de um manipulador de tipos.
#### Dapper.Contrib
`GetAll()` e `Get(id)` funcionam. `Insert()` não — ele gera sintaxe do SQL Server (`SCOPE_IDENTITY`, `[]`). Recomenda-se usar, em vez disso, o método nativo `InsertBinaryAsync` do `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);
```
Os nomes das propriedades devem corresponder exatamente aos nomes de coluna do ClickHouse (diferenciam maiúsculas de minúsculas).
#### Limitações
| O que | Status | Detalhes |
| ------------------------------ | ------------- | ------------------------------------------------------------------------------- |
| Tuple como **resultado** | Funciona | Requer o registro de `SqlMapper.TypeHandler` |
| Tuple como **parâmetro** | Não suportado | O Dapper não consegue serializar `ITuple`/`Tuple<>` como valor de `DbParameter` |
| Tipos aninhados como parâmetro | Não suportado | Pelo mesmo motivo — o Dapper rejeita tipos complexos como valores de parâmetro |
| Tipos Geo como parâmetro | Não suportado | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | Não suportado | Gera sintaxe específica do SQL Server |
| Tipo `Nothing` | Não suportado | Sem representação significativa no .NET |
### Linq2db
Este driver é compatível com o [linq2db](https://github.com/linq2db/linq2db), um ORM leve e provedor LINQ para .NET. Consulte o site do projeto para obter a documentação detalhada.
**Exemplo de uso:**
Crie uma `DataConnection` usando o provedor do 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);
```
Os mapeamentos de tabelas podem ser definidos usando atributos ou a API fluente. Se os nomes da sua classe e propriedade corresponderem exatamente aos nomes da tabela e da coluna, nenhuma configuração será necessária:
```csharp theme={null}
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
```
**Consultando:**
```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();
```
**Cópia em lote:**
Use `BulkCopyAsync` para inserções em lote eficientes.
```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
O provedor oficial do Entity Framework Core para ClickHouse. Mapeie classes C# para tabelas do ClickHouse, faça consultas com LINQ e insira dados via `SaveChanges` — tudo usando os padrões familiares do EF Core.
* **NuGet**: [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **Código-fonte**: [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
Este provedor está em desenvolvimento ativo. O lançamento atual oferece suporte a consultas LINQ (incluindo junções, subconsultas e operações de conjunto), `INSERT` via `SaveChanges` / `BulkInsertAsync`, migrations com DDL completo (CREATE / ALTER / DROP) e configuração específica do motor de tabela do ClickHouse. `UPDATE` / `DELETE` não são suportados.
#### Instalação
```bash theme={null}
dotnet add package ClickHouse.EntityFrameworkCore
```
Requer o .NET 10.0 e o EF Core 10.
#### Início rápido
Defina sua entidade e o `DbContext` e, em seguida, consulte com 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 com suporte
| Categoria | Tipos do ClickHouse | Tipos CLR |
| --------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Inteiros** | `Int8`–`Int64`, `UInt8`–`UInt64` | `sbyte`, `short`, `int`, `long`, `byte`, `ushort`, `uint`, `ulong` |
| **Inteiros grandes** | `Int128`, `Int256`, `UInt128`, `UInt256` | `BigInteger` |
| **Pontos flutuantes** | `Float32`, `Float64`, `BFloat16` | `float`, `double` |
| **Decimais** | `Decimal(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` ou `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **Strings** | `String`, `FixedString(N)` | `string` |
| **Enums** | `Enum8(...)`, `Enum16(...)` | `string` ou `enum` de C# |
| **Data/hora** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **Time** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **Rede** | `IPv4`, `IPv6` | `IPAddress` |
| **Arrays** | `Array(T)` | `T[]`, `List`, `IList`, `ICollection`, `IReadOnlyList`, `IReadOnlyCollection`, `IEnumerable` |
| **Maps** | `Map(K, V)` | `Dictionary` |
| **Tuples** | `Tuple(T1, ...)` | `Tuple<...>` ou `ValueTuple<...>` |
| **Variant** | `Variant(T1, T2, ...)` | `object` |
| **Dinâmico** | `Dynamic` | `object` |
| **JSON** | `Json` | `JsonNode` ou `string` |
| **Geoespaciais** | `Point`, `Ring`, `LineString`, `Polygon`, `MultiLineString`, `MultiPolygon`, `Geometry` | `Tuple` e arrays correspondentes; `object` para `Geometry` |
| **Wrappers** | `Nullable(T)`, `LowCardinality(T)` | Desempacotados automaticamente |
Use `ClickHouseDecimal` (de `ClickHouse.Driver.Numerics`) em vez de `decimal` quando precisar da precisão total de colunas `Decimal128`/`Decimal256` — o `decimal` do .NET é limitado a 28–29 dígitos significativos.
#### Operações LINQ compatíveis
**Consultas:** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY e agregações:** `GroupBy` com `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` — incluindo `HAVING` (`.Where()` após `.GroupBy()`), várias agregações em uma única projeção e `OrderBy` com base nos resultados agregados.
**JOINs:** `Join` (INNER), padrões `GroupJoin`/`SelectMany` (LEFT e CROSS). LEFT JOIN retorna `null` de fato para linhas sem correspondência (veja [semântica de `null` em LEFT JOIN](#ef-core-join-nulls) abaixo).
**Subconsultas:** `Contains` / `IN` correlacionados, `Any` / `EXISTS`, `All` e subconsultas escalares em projeções.
**Operações de conjunto:** `Concat` (→ `UNION ALL`), `Union` (→ `UNION DISTINCT`), `Intersect`, `Except`.
**Coleções locais inline:** junções e `Contains` em coleções em memória (`int[]`, `List`, etc.) são convertidos em uma série de UNIONs.
**Métodos de string:** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (e o operador `+`).
**Funções matemáticas:** métodos padrão de `Math` e `MathF` traduzidos para seus equivalentes no ClickHouse — funções aritméticas, logarítmicas, trigonométricas e utilitárias.
##### Semântica de NULL em LEFT JOIN
O provider injeta `set_join_use_nulls=1` automaticamente em cada conexão para atender às expectativas do Entity Framework em relação ao comportamento de JOIN.
Se o seu servidor ClickHouse ou profile impedir a alteração dessa configuração (por exemplo, um profile `readonly=1`), desative isso com:
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
Com o opt-out ativado, o LEFT JOIN retorna os valores padrão das colunas do ClickHouse, e a detecção de navegação baseada em nulos do EF não funciona mais como esperado. Use comparações explícitas com `0` / `""` em vez de `== null`.
#### Inserção de dados
`SaveChanges` usa a API nativa `InsertBinaryAsync` do driver — codificação RowBinary com compressão GZip, muito mais eficiente do que SQL parametrizado:
```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();
```
As entidades passam de `Added` para `Unchanged` após salvar, assim como em qualquer outro provedor do EF Core.
**O tamanho do lote** é configurável (padrão: 1000):
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### Inserção em massa
Para cargas de alta taxa de transferência, use `BulkInsertAsync` em vez de `SaveChanges`. Esse é um método de extensão no `DbContext` que ignora completamente o rastreador de alterações, a resolução de identidade e o gerenciamento de estado do EF Core — ele chama diretamente o `InsertBinaryAsync` do driver com codificação RowBinary e compressão GZip.
Isso o torna ideal para carregar grandes conjuntos de dados quando você não precisa rastrear entidades após a inserção:
```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);
```
A entrada pode ser qualquer `IEnumerable` — ela processa as entidades em fluxo, sem carregá-las todas na memória. O valor retornado é o número de linhas inseridas. As entidades **não** ficam vinculadas ao `DbContext` após a inserção, portanto não há transição de estado de `Added` → `Unchanged`.
#### Enums
As colunas `Enum8`/`Enum16` do ClickHouse podem ser mapeadas como propriedades `string` ou como tipos `enum` em C#. Ao usar enums em C#, o provedor converte automaticamente entre o enum e sua representação textual:
```csharp theme={null}
public enum Status { Active, Inactive, Pending }
public class User
{
public long Id { get; set; }
public Status Status { get; set; }
}
// Consulta com valores do enum
var active = await ctx.Users
.Where(u => u.Status == Status.Active)
.ToListAsync();
```
#### Conversões de tipos personalizadas
O sistema `ValueConverter` do EF Core permite mapear tipos personalizados para tipos que o provedor já suporta. O provedor nunca vê seu tipo personalizado — o EF Core faz a conversão na interface entre os dois.
**Conversão por propriedade:**
```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; }
}
// No 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");
```
**Classe de conversor reutilizável:**
```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 uma única propriedade:
.HasConversion()
// Ou a todas as propriedades de um tipo por convenção:
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
configurationBuilder.Properties()
.HaveConversion();
}
```
#### Anotações de tipo de coluna
Para tipos escalares como `string`, `int`, `DateTime` etc., o provedor deduz automaticamente o tipo do ClickHouse. Para tipos parametrizados e wrappers, é necessário especificar explicitamente o tipo do ClickHouse.
**Usando anotações de dados (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; }
}
```
**Usando a API fluente no `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)");
});
```
Wrappers aninhados como `Array(Nullable(Int32))` e `LowCardinality(Nullable(String))` são suportados — o provedor desempacota `Nullable` e `LowCardinality` automaticamente em todos os níveis de aninhamento.
#### Colunas Variant e Dynamic
As colunas `Variant(T1, T2, ...)` e `Dynamic` do ClickHouse são mapeadas para `object` no .NET. Como `object` é genérico demais para a inferência automática de tipos, você deve declarar explicitamente o tipo de armazenamento por meio de `.HasColumnType()`:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public object? Payload { get; set; }
}
// No OnModelCreating:
entity.Property(e => e.Payload).HasColumnType("Variant(String, UInt64, Array(UInt64))");
// ou:
entity.Property(e => e.Payload).HasColumnType("Dynamic");
```
Ao ler, o valor é desserializado automaticamente para o tipo .NET correspondente ao discriminador armazenado (por exemplo, `string`, `ulong`, `ulong[]`).
#### Colunas JSON
O provedor dá suporte ao tipo de coluna `Json` do ClickHouse, com mapeamento para `System.Text.Json.Nodes.JsonNode` (principal) ou `string` (via `ValueConverter` automático):
```csharp theme={null}
using System.Text.Json.Nodes;
public class Event
{
public long Id { get; set; }
public JsonNode? Data { get; set; }
}
// No OnModelCreating:
entity.Property(e => e.Data).HasColumnType("Json");
```
A leitura e a escrita de JSON funcionam tanto com `SaveChanges` quanto com `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"
```
Se você preferir strings JSON brutas, mapeie a propriedade como `string`, com o tipo de coluna `Json` — o provedor aplica um `ValueConverter` automaticamente:
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public string? Data { get; set; } // JSON bruto como string
}
entity.Property(e => e.Data).HasColumnType("Json");
```
* **Sem tradução de caminhos JSON** — `entity.Data["name"]` no LINQ não é convertido para a sintaxe SQL `data.name` do ClickHouse. Filtre colunas não JSON e inspecione o JSON na memória.
* **Semântica de NULL** — o tipo JSON do ClickHouse retorna `{}` (objeto vazio) para valores NULL, em vez de SQL NULL.
* **Precisão de inteiros** — o JSON do ClickHouse armazena todos os inteiros como `Int64`. Ao ler com `JsonNode`, use `GetValue()` em vez de `GetValue()`.
#### Motores de tabela
Configure os motores de tabela do ClickHouse e as cláusulas específicas de cada motor por meio da API fluente `ToTable(name, t => ...)`. Quando nenhum motor é configurado, o provedor usa `MergeTree`, com `ORDER BY` derivado da chave primária da entidade.
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("events", t => t
.HasMergeTreeEngine()
.WithOrderBy("UserId", "Timestamp")
.WithPartitionBy("toYYYYMM(Timestamp)")
.WithPrimaryKey("UserId")
.WithSettings("index_granularity = 8192"));
});
```
Famílias de motores compatíveis:
| Motor | Método fluente | Observações |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `MergeTree` | `HasMergeTreeEngine()` | Padrão quando nada é configurado |
| `ReplacingMergeTree` | `HasReplacingMergeTreeEngine("Version", "IsDeleted")` ou `HasReplacingMergeTreeEngine(e => e.Version)` | Colunas Version / IsDeleted opcionais |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` ou `HasSummingMergeTreeEngine(e => new { … })` | Colunas a somar opcionais |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` ou `HasCollapsingMergeTreeEngine(e => e.Sign)` | A coluna `Sign` deve ser `Int8` |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` ou `(e => e.Sign, e => e.Version)` | — |
| `GraphiteMergeTree` | `HasGraphiteMergeTreeEngine("config_section")` | — |
| `Log`, `TinyLog`, `StripeLog`, `Memory` | `HasLogEngine()`, `HasTinyLogEngine()`, `HasStripeLogEngine()`, `HasMemoryEngine()` | Sem ORDER BY / PARTITION BY |
**Cláusulas do motor:** `WithOrderBy`, `WithPartitionBy`, `WithPrimaryKey`, `WithSampleBy`, `WithTtl`, `WithSettings`. Todas são anexadas ao construtor de motor retornado por `HasXxxEngine()`.
**Recursos em nível de coluna:** `HasCodec`, `HasTtl`, `HasComment`, `HasDefault` — todos participam das migrações.
**Índices de data skipping** — via `HasIndex(...).HasSkippingIndexType(...)`:
```csharp theme={null}
modelBuilder.Entity()
.HasIndex(e => e.UserId)
.HasSkippingIndexType("minmax")
.HasGranularity(4);
// Índice com parâmetros (ex.: bloom_filter, tokenbf_v1):
modelBuilder.Entity()
.HasIndex(e => e.Tag)
.HasSkippingIndexType("bloom_filter")
.HasSkippingIndexParams("0.01")
.HasGranularity(1);
```
Índices padrão (sem skipping) são ignorados silenciosamente, já que não têm equivalente no ClickHouse. Índices únicos geram exceção, pois o ClickHouse não impõe unicidade.
#### Migrações
Fluxo de trabalho padrão das migrações do EF Core:
```bash theme={null}
dotnet ef migrations add InitialCreate
dotnet ef database update
```
Operações suportadas:
| Operação | Emite |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `CREATE TABLE` | Inclui cláusula de motor, ORDER BY, PARTITION BY, SETTINGS, codecs/TTL/comentários/valores padrão de coluna |
| `ALTER TABLE ADD COLUMN` | — |
| `ALTER TABLE DROP COLUMN` | — |
| `ALTER TABLE MODIFY COLUMN` | Lida com alteração de tipo e adição/remoção de anotações (CODEC, TTL, COMMENT, DEFAULT) |
| `ALTER TABLE RENAME COLUMN` | — |
| `RENAME TABLE` | — |
| `ALTER TABLE ADD INDEX` / `DROP INDEX` | Somente índices de data skipping |
| `CREATE DATABASE` / `DROP DATABASE` | Via `EnsureCreated` / `EnsureDeleted` e migrações |
#### Limitações de migração
| Recurso | Motivo |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Chaves estrangeiras | O ClickHouse não aplica chaves estrangeiras. As migrações rejeitam `AddForeignKey`; o validador do modelo emite um aviso na compilação do modelo. |
| Restrições de unicidade / índices únicos | O ClickHouse não aplica unicidade. Índices únicos geram erro no momento da migração. |
| Valores gerados pelo servidor (auto-incremento / `IDENTITY`) | O ClickHouse não tem equivalente. |
| colunas `Nested(…)` | Ainda não há suporte como tipo CLR mapeado. |
| Entidades de propriedade como JSON (`.ToJson()`) | O mapeamento estrutural de JSON para entidades de propriedade ainda não foi implementado. Em vez disso, use `JsonNode` / `string` em uma coluna `Json` (consulte [colunas JSON](#ef-core-json)). |
Além das migrações, o provedor também ainda não oferece suporte a:
* **`UPDATE` / `DELETE`**
* **Transações**: `BeginTransaction` é um no-op. Não há suporte a transações ACID no ClickHouse.
* **Tradução de consultas com caminho JSON**: `entity.Data["key"]` em LINQ não é traduzido para a sintaxe SQL `data.key` do ClickHouse. Aplique filtros em colunas não JSON e inspecione o JSON na memória.
## Limitações
### Colunas do tipo AggregateFunction
Colunas do tipo `AggregateFunction(...)` não podem ser consultadas nem inseridas diretamente.
Para inserir:
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
Para selecionar:
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***