()` avant la sérialisation. Toute tentative de sérialiser un type non enregistré lève une `ClickHouseJsonSerializationException`.
* Les propriétés de type Dictionary et array/list nécessitent des indications de type dans la définition de la colonne pour être sérialisées correctement. Sans ces indications, utilisez plutôt String mode.
* Les valeurs nulles des propriétés POCO ne sont écrites que lorsque le chemin possède une indication de type `Nullable(T)` dans la définition de la colonne. ClickHouse n’autorise pas les types `Nullable` dans les chemins JSON dynamiques ; les propriétés nulles sans indication sont donc ignorées.
* Les attributs `ClickHouseJsonPath` et `ClickHouseJsonIgnore` sont ignorés en String mode (ils ne fonctionnent qu’en mode binaire).
***
#### Autres types
| Type ClickHouse | Types .NET acceptés | Remarques |
| ----------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| UUID | `Guid`, `string` | Chaîne analysée comme un Guid |
| IPv4 | `IPAddress`, `string` | Doit être une adresse IPv4 ; chaîne analysée via `IPAddress.Parse()` |
| IPv6 | `IPAddress`, `string` | Doit être une adresse IPv6 ; chaîne analysée via `IPAddress.Parse()` |
| Nothing | N’importe quel type | N’écrit rien (no-op) |
| Dynamic | — | **Non pris en charge** (lève `NotImplementedException`) |
| Array(T) | `IList`, `null` | `null` écrit un tableau vide |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | Le nombre d’éléments doit correspondre à l’arité du tuple |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull` ou types acceptés par T | Écrit l’octet indicateur de null avant la valeur |
| Enum8 | `string`, `sbyte`, types numériques | La chaîne est recherchée dans le dictionnaire de l’enum |
| Enum16 | `string`, `short`, types numériques | La chaîne est recherchée dans le dictionnaire de l’enum |
| LowCardinality(T) | Types acceptés par T | Délègue au type sous-jacent |
| SimpleAggregateFunction | Types acceptés par le type sous-jacent | Délègue au type sous-jacent |
| Nested(...) | `IList` de tuples | Le nombre d’éléments doit correspondre au nombre de champs |
| Variant(T1, T2, ...) | Valeur correspondant à l’un de T1, T2, ... | Lève `ArgumentException` si aucun type ne correspond |
| QBit(T, dim) | `IList` | Délègue à Array ; la dimension n’est qu’une métadonnée |
***
#### Types de géométrie
| Type ClickHouse | Types .NET acceptés | Remarques |
| --------------- | ------------------------------------------------------ | --------------------------------------- |
| Point | `System.Drawing.Point`, `ITuple`, `IList` (2 éléments) | |
| Ring | `IList` de Point | |
| LineString | `IList` de Point | |
| Polygon | `IList` de Ring | |
| MultiLineString | `IList` de LineString | |
| MultiPolygon | `IList` de Polygon | |
| Geometry | N'importe quel type de géométrie ci-dessus | Variante de tous les types de géométrie |
***
#### Non pris en charge en écriture
| ClickHouse Type | Remarques |
| ----------------- | --------------------------------- |
| Dynamic | Lève `NotImplementedException` |
| AggregateFunction | Lève `AggregateFunctionException` |
***
### Gestion du type Nested
Les types Nested de ClickHouse (`Nested(...)`) peuvent être lus et écrits avec la sémantique des tableaux.
```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 }
);
```
## Journalisation et diagnostics
Le client .NET ClickHouse s’intègre aux abstractions `Microsoft.Extensions.Logging` afin d’offrir une journalisation légère, activée sur demande. Lorsqu’elle est activée, le driver émet des messages structurés pour les événements du cycle de vie de la connexion, l’exécution des commandes, les opérations de transport et les opérations d’insertion en masse. La journalisation est entièrement facultative : les applications qui ne configurent pas de logger continuent de s’exécuter sans surcharge supplémentaire.
### Démarrage rapide
```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);
```
#### Utilisation du fichier appsettings.json
Vous pouvez configurer les niveaux de journalisation à l’aide de la configuration .NET standard :
```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);
```
#### Utilisation d’une configuration en mémoire
Vous pouvez également configurer le niveau de verbosité de la journalisation par catégorie dans le code :
```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);
```
### Catégories et émetteurs
Le driver utilise des catégories dédiées afin de vous permettre d’ajuster finement les niveaux de journalisation par composant :
| Catégorie | Source | Points clés |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `ClickHouse.Driver.Connection` | `ClickHouseConnection` | Cycle de vie de la connexion, sélection de la fabrique de clients HTTP, ouverture/fermeture de la connexion, gestion des sessions. |
| `ClickHouse.Driver.Command` | `ClickHouseCommand` | Début/fin d’exécution des requêtes, durée d’exécution, ID de requête, statistiques du serveur et détails des erreurs. |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | Requêtes HTTP streaming de bas niveau, indicateurs de compression, codes d’état des réponses et échecs de transport. |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | Insertions binaires, requêtes et autres opérations |
| `ClickHouse.Driver.NetTrace` | `TraceHelper` | Traçage réseau, uniquement lorsque le mode débogage est activé |
#### Exemple : diagnostic des problèmes de connexion
```json theme={null}
{
"Logging": {
"LogLevel": {
"ClickHouse.Driver.Connection": "Trace",
"ClickHouse.Driver.Transport": "Trace"
}
}
}
```
Les éléments suivants seront consignés :
* Sélection de la fabrique de clients HTTP (pool par défaut ou connexion unique)
* Configuration du gestionnaire HTTP (SocketsHttpHandler ou HttpClientHandler)
* Paramètres du pool de connexions (MaxConnectionsPerServer, PooledConnectionLifetime, etc.)
* Paramètres de délai d’expiration (ConnectTimeout, Expect100ContinueTimeout, etc.)
* Configuration SSL/TLS
* Événements d’ouverture/fermeture des connexions
* Suivi des ID de session
### Mode Débogage : tracing réseau et diagnostics
Pour faciliter le diagnostic des problèmes réseau, la bibliothèque du driver inclut un utilitaire qui active le tracing de bas niveau des mécanismes réseau internes de .NET. Pour l’activer, vous devez fournir une instance de LoggerFactory avec le niveau défini sur Trace, et définir EnableDebugMode sur true (ou l’activer manuellement via la classe `ClickHouse.Driver.Diagnostic.TraceHelper`). Les événements seront consignés dans la catégorie `ClickHouse.Driver.NetTrace`. Avertissement : cela générera des logs extrêmement verbeux et aura un impact sur les performances. Il n’est pas recommandé d’activer le mode Débogage en production.
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // Must be Trace level to see network events
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // Enable low-level network tracing
};
```
## OpenTelemetry
Le driver intègre une prise en charge native du tracing distribué avec OpenTelemetry via l’API .NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing). Lorsqu’il est activé, le driver émet des spans pour les opérations sur la base de données, qui peuvent être exportés vers des backends d’observabilité comme Jaeger ou ClickHouse lui-même (via l’[OpenTelemetry Collector](/fr/guides/use-cases/observability/build-your-own/integrating-opentelemetry)).
### Activer le tracing
Dans les applications ASP.NET Core, ajoutez l’`ActivitySource` du driver ClickHouse à votre configuration OpenTelemetry :
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // Subscribe to ClickHouse driver spans
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()); // Or AddJaegerExporter(), etc.
```
Pour les applications en ligne de commande, les tests ou la configuration manuelle :
```csharp theme={null}
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName)
.AddConsoleExporter()
.Build();
```
### Attributs des spans
Chaque span inclut les attributs de base de données standard d’OpenTelemetry, ainsi que des statistiques de requête propres à ClickHouse utiles pour le débogage.
| Attribut | Description |
| ----------------------------- | ---------------------------------------------- |
| `db.system` | Toujours `"clickhouse"` |
| `db.name` | Nom de la base de données |
| `db.user` | Nom d’utilisateur |
| `db.statement` | Requête SQL (si activée) |
| `db.clickhouse.read_rows` | Lignes lues par la requête |
| `db.clickhouse.read_bytes` | Octets lus par la requête |
| `db.clickhouse.written_rows` | Lignes écrites par la requête |
| `db.clickhouse.written_bytes` | Octets écrits par la requête |
| `db.clickhouse.elapsed_ns` | Temps d’exécution côté serveur en nanosecondes |
### Options de configuration
Contrôlez le comportement du tracing à l’aide de `ClickHouseDiagnosticsOptions` :
```csharp theme={null}
using ClickHouse.Driver.Diagnostic;
// Include SQL statements in spans (default: false for security)
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// Truncate long SQL statements (default: 1000 characters)
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
L’activation de `IncludeSqlInActivityTags` peut exposer des données sensibles dans vos traces. À utiliser avec prudence dans les environnements de production.
## Configuration TLS
Lorsque vous vous connectez à ClickHouse via HTTPS, vous pouvez configurer le comportement de TLS/SSL de plusieurs manières.
### Validation personnalisée des certificats
Pour les environnements de production nécessitant une logique de validation des certificats personnalisée, fournissez votre propre `HttpClient` avec un gestionnaire `ServerCertificateCustomValidationCallback` configuré :
```csharp theme={null}
using System.Net;
using System.Net.Security;
using ClickHouse.Driver;
var handler = new HttpClientHandler
{
// Required when compression is enabled (default)
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
ServerCertificateCustomValidationCallback = (message, cert, chain, sslPolicyErrors) =>
{
// Example: Accept a specific certificate thumbprint
if (cert?.Thumbprint == "YOUR_EXPECTED_THUMBPRINT")
return true;
// Example: Accept certificates from a specific issuer
if (cert?.Issuer.Contains("YourOrganization") == true)
return true;
// Default: Use standard validation
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);
```
Points importants à prendre en compte lors de la fourniture d’un HttpClient personnalisé
* **Décompression automatique** : vous devez activer `AutomaticDecompression` si la compression n’est pas désactivée (elle est activée par défaut).
* **Délai d’inactivité** : définissez `PooledConnectionIdleTimeout` sur une valeur inférieure au `keep_alive_timeout` du serveur (10 secondes pour ClickHouse Cloud) afin d’éviter les erreurs de connexion dues à des connexions semi-ouvertes.
## Prise en charge des ORM
Les ORM nécessitent l’API ADO.NET (`ClickHouseConnection`). Pour gérer correctement le cycle de vie des connexions, créez-les à partir d’un `ClickHouseDataSource` :
```csharp theme={null}
// Register DataSource as singleton
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default");
// Create connections for ORM use
await using var connection = await dataSource.OpenConnectionAsync();
// Pass connection to your ORM...
```
### Dapper
`ClickHouse.Driver` est compatible avec Dapper. Le pilote convertit automatiquement la syntaxe `@parameter` de Dapper en syntaxe native `{parameter:Type}` de ClickHouse, en déduisant les types à partir des valeurs .NET.
Utilisez `ClickHouseDataSource` pour gérer correctement le cycle de vie de la connexion :
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // Register as singleton in DI
using var connection = dataSource.CreateConnection();
```
#### Modes de passage des paramètres
Tous les modes standard de passage des paramètres de Dapper sont pris en charge :
**Objets anonymes :**
```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 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);
```
**Dictionnaire :**
```csharp theme={null}
var parameters = new Dictionary { { "Id", 2 } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", parameters);
```
**`DynamicParameters` (à partir d’un dictionnaire ou d’un objet anonyme) :**
```csharp theme={null}
var dynParams = new DynamicParameters(new { Id = 1 });
// or: new DynamicParameters(new Dictionary { { "Id", 1 } });
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", dynParams);
```
#### Requêtes vers des POCO
Dapper associe les colonnes aux propriétés par leur nom (sans tenir compte de la casse) :
```csharp theme={null}
class User
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
// From a table
var users = (await connection.QueryAsync("SELECT id, name, balance FROM users")).ToList();
// From a literal
var row = (await connection.QueryAsync("SELECT 1 as id, 'hello' as name, 2.5 as balance")).Single();
```
#### Syntaxe native des paramètres ClickHouse
Lorsque vous avez besoin d'un contrôle explicite des types, utilisez directement dans le SQL la syntaxe `{param:Type}` de ClickHouse avec un `Dictionary` pour les valeurs de paramètre. N'utilisez pas à la fois la syntaxe `@param` et la syntaxe `{param:Type}` pour un même paramètre.
```csharp theme={null}
var parameters = new Dictionary { { "value", 42 } };
var result = await connection.QueryAsync("SELECT {value:Int32}", parameters);
```
#### WHERE IN
**L’expansion native de IN dans Dapper fonctionne :**
```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 réécrit cela en `WHERE id IN (@Ids1, @Ids2, @Ids3)`, et le driver convertit chaque paramètre étendu.
**La fonction `has()` de ClickHouse avec un paramètre Array fonctionne également :**
```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);
```
#### Gestionnaires de types personnalisés
Certains types ClickHouse, par exemple `ITuple`, `BigInteger` et `ClickHouseDecimal`, nécessitent l’enregistrement de gestionnaires au démarrage :
```csharp theme={null}
// ClickHouseDecimal (for Decimal64/128/256 columns)
SqlMapper.AddTypeHandler(new ClickHouseDecimalHandler());
// BigInteger (for Int128/Int256/UInt128/UInt256 columns)
SqlMapper.AddTypeHandler(new BigIntegerHandler());
// IPAddress (for IPv4/IPv6 columns)
SqlMapper.AddTypeHandler(new IpAddressHandler());
```
Voir l’[exemple Dapper](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/ORM/ORM_001_Dapper.cs) pour un exemple d’implémentation d’un type handler.
#### Dapper.Contrib
`GetAll()` et `Get(id)` fonctionnent. En revanche, `Insert()` ne fonctionne pas : il génère une syntaxe SQL Server (`SCOPE_IDENTITY`, `[]`). Il est recommandé d’utiliser à la place la méthode native `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);
```
Les noms des propriétés doivent correspondre exactement aux noms de colonnes de ClickHouse (respect de la casse).
#### Limitations
| Élément | Statut | Détails |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------ |
| Tuple comme **résultat** | Fonctionne | Nécessite l’enregistrement de `SqlMapper.TypeHandler` |
| Tuple comme **paramètre** | Non pris en charge | Dapper ne peut pas sérialiser `ITuple`/`Tuple<>` en tant que valeur de `DbParameter` |
| Types Nested comme paramètre | Non pris en charge | Même raison — Dapper rejette les types complexes comme valeurs de paramètre |
| Types Geo comme paramètre | Non pris en charge | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | Non pris en charge | Génère une syntaxe spécifique à SQL Server |
| Type `Nothing` | Non pris en charge | Aucune représentation .NET pertinente |
### Linq2db
Ce pilote est compatible avec [linq2db](https://github.com/linq2db/linq2db), un ORM léger et un fournisseur LINQ pour .NET. Consultez le site du projet pour une documentation détaillée.
**Exemple d’utilisation :**
Créez une `DataConnection` à l’aide du fournisseur 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);
```
Les mappages de tables peuvent être définis à l’aide d’attributs ou de l’API fluide. Si les noms de votre classe et de vos propriétés correspondent exactement aux noms de la table et des colonnes, aucune configuration n’est nécessaire :
```csharp theme={null}
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
```
**Requêtes :**
```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();
```
**Bulk Copy :**
Utilisez `BulkCopyAsync` pour effectuer efficacement des insertions en bloc.
```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
Le fournisseur officiel Entity Framework Core pour ClickHouse. Associez des classes C# à des tables ClickHouse, effectuez des requêtes avec LINQ et insérez des données via `SaveChanges` — le tout avec les conventions EF Core habituelles.
* **NuGet** : [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **Source** : [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
Ce fournisseur est activement développé. La version actuelle prend en charge les requêtes LINQ (y compris les JOIN, les sous-requêtes et les opérations ensemblistes), `INSERT` via `SaveChanges` / `BulkInsertAsync`, les migrations avec DDL complet (CREATE / ALTER / DROP), ainsi que la configuration du moteur de table spécifique à ClickHouse. `UPDATE` / `DELETE` ne sont pas pris en charge.
#### Installation
```bash theme={null}
dotnet add package ClickHouse.EntityFrameworkCore
```
Nécessite .NET 10.0 et EF Core 10.
#### Démarrage rapide
Définissez votre entité et le `DbContext`, puis effectuez des requêtes avec 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");
}
// Query
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();
```
#### Types pris en charge
| Catégorie | Types ClickHouse | Types CLR |
| ------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Entiers** | `Int8`–`Int64`, `UInt8`–`UInt64` | `sbyte`, `short`, `int`, `long`, `byte`, `ushort`, `uint`, `ulong` |
| **Grands entiers** | `Int128`, `Int256`, `UInt128`, `UInt256` | `BigInteger` |
| **Flottants** | `Float32`, `Float64`, `BFloat16` | `float`, `double` |
| **Décimaux** | `Decimal(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` ou `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **Chaînes** | `String`, `FixedString(N)` | `string` |
| **Énumérations** | `Enum8(...)`, `Enum16(...)` | `string` ou `enum` C# |
| **Date/heure** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **Heure** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **Réseau** | `IPv4`, `IPv6` | `IPAddress` |
| **Tableaux** | `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` |
| **Dynamic** | `Dynamic` | `object` |
| **JSON** | `Json` | `JsonNode` ou `string` |
| **Géographiques** | `Point`, `Ring`, `LineString`, `Polygon`, `MultiLineString`, `MultiPolygon`, `Geometry` | `Tuple` et les tableaux correspondants ; `object` pour `Geometry` |
| **Wrappers** | `Nullable(T)`, `LowCardinality(T)` | Déballés automatiquement |
Utilisez `ClickHouseDecimal` (de `ClickHouse.Driver.Numerics`) au lieu de `decimal` lorsque vous avez besoin de toute la précision des colonnes `Decimal128`/`Decimal256` — `decimal` en .NET est limité à 28–29 chiffres significatifs.
#### Opérations LINQ prises en charge
**Requêtes :** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY et agrégats :** `GroupBy` avec `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` — y compris `HAVING` (`.Where()` après `.GroupBy()`), plusieurs agrégats dans une même projection et `OrderBy` sur les résultats agrégés.
**JOINs :** `Join` (INNER), schémas `GroupJoin`/`SelectMany` (LEFT et CROSS). LEFT JOIN renvoie de vraies valeurs `null` pour les lignes sans correspondance (voir [la sémantique des valeurs nulles de LEFT JOIN](#ef-core-join-nulls) ci-dessous).
**Sous-requêtes :** `Contains` / `IN` corrélés, `Any` / `EXISTS`, `All`, et sous-requêtes scalaires dans les projections.
**Opérations ensemblistes :** `Concat` (→ `UNION ALL`), `Union` (→ `UNION DISTINCT`), `Intersect`, `Except`.
**Collections locales en mémoire :** les joins et `Contains` sur des collections en mémoire (`int[]`, `List`, etc.) sont traduits en une série de `UNION`.
**Méthodes de chaîne :** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (et l’opérateur `+`).
**Fonctions mathématiques :** les méthodes standard de `Math` et `MathF` sont traduites en leurs équivalents ClickHouse — fonctions arithmétiques, logarithmiques, trigonométriques et utilitaires.
##### Sémantique des valeurs nulles de LEFT JOIN
Le fournisseur injecte automatiquement `set_join_use_nulls=1` dans chaque chemin de connexion afin de correspondre aux attentes d'Entity Framework concernant le comportement des JOIN.
Si votre serveur ClickHouse ou votre profil interdit la modification de ce paramètre (par exemple, un profil `readonly=1`), désactivez ce comportement avec :
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
Lorsque l’opt-out est activé, LEFT JOIN renvoie les valeurs par défaut des colonnes ClickHouse, et la détection par EF des propriétés de navigation basée sur les valeurs nulles ne fonctionne plus comme prévu. Utilisez des comparaisons explicites avec `0` / `""` plutôt que `== null`.
#### Insertion de données
`SaveChanges` utilise l’API native `InsertBinaryAsync` du pilote — l’encodage RowBinary avec compression GZip est bien plus efficace que le SQL paramétré :
```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();
```
Les entités passent de `Added` à `Unchanged` après la sauvegarde, comme avec tout autre fournisseur EF Core.
La **taille du lot** est configurable (1000 par défaut) :
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### Insertion en masse
Pour les chargements à haut débit, utilisez `BulkInsertAsync` au lieu de `SaveChanges`. Il s’agit d’une méthode d’extension sur `DbContext` qui contourne entièrement le suivi des modifications d’EF Core, la résolution des identités et la gestion d’état — elle appelle directement `InsertBinaryAsync` du pilote avec l’encodage RowBinary et la compression GZip.
Cette méthode convient donc au chargement de grands ensembles de données lorsque vous n’avez pas besoin du suivi des entités après l’insertion :
```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);
```
L’entrée peut être n’importe quel `IEnumerable` — les entités sont traitées en flux, sans être toutes chargées en mémoire. La valeur de retour est le nombre de lignes insérées. Les entités ne sont **pas** rattachées au `DbContext` après l’insertion, il n’y a donc pas de transition d’état `Added` → `Unchanged`.
#### Énumérations
Les colonnes ClickHouse `Enum8`/`Enum16` peuvent être mappées sur des propriétés `string` ou sur des types C# `enum`. Lorsqu’on utilise des énumérations C#, le fournisseur convertit automatiquement l’énumération depuis et vers sa représentation sous forme de chaîne :
```csharp theme={null}
public enum Status { Active, Inactive, Pending }
public class User
{
public long Id { get; set; }
public Status Status { get; set; }
}
// Query with enum values
var active = await ctx.Users
.Where(u => u.Status == Status.Active)
.ToListAsync();
```
#### Conversions de type personnalisées
Le système `ValueConverter` d’EF Core vous permet d’associer des types personnalisés à des types déjà pris en charge par le fournisseur. Le fournisseur ne voit jamais votre type personnalisé — EF Core effectue la conversion à la limite entre les deux.
**Conversion par propriété :**
```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; }
}
// In 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 convertisseur réutilisable :**
```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] };
}
}
// Apply to a single property:
.HasConversion()
// Or apply to all properties of a type via conventions:
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
configurationBuilder.Properties()
.HaveConversion();
}
```
#### Annotations de type de colonne
Pour les types scalaires comme `string`, `int`, `DateTime`, etc., le fournisseur détermine automatiquement le type ClickHouse. Pour les types paramétrés et les wrappers, vous devez spécifier explicitement le type ClickHouse.
**Utilisation des annotations de données (attributs) :**
```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; }
}
```
**Utilisation de l’API fluide dans `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)");
});
```
Les wrappers imbriqués comme `Array(Nullable(Int32))` et `LowCardinality(Nullable(String))` sont pris en charge — le fournisseur retire automatiquement les wrappers `Nullable` et `LowCardinality` à chaque niveau d’imbrication.
#### Colonnes Variant et Dynamic
Dans .NET, les colonnes ClickHouse `Variant(T1, T2, ...)` et `Dynamic` sont mappées à `object`. Comme `object` est trop générique pour une inférence de type automatique, vous devez déclarer explicitement le type de stockage via `.HasColumnType()` :
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public object? Payload { get; set; }
}
// In OnModelCreating:
entity.Property(e => e.Payload).HasColumnType("Variant(String, UInt64, Array(UInt64))");
// or:
entity.Property(e => e.Payload).HasColumnType("Dynamic");
```
Lors de la lecture, la valeur est automatiquement désérialisée dans le type .NET correspondant au discriminateur stocké (par ex. `string`, `ulong`, `ulong[]`).
#### Colonnes JSON
Le fournisseur prend en charge le type de colonne `Json` de ClickHouse, qu’il associe à `System.Text.Json.Nodes.JsonNode` (par défaut) ou à `string` (via un `ValueConverter` automatique) :
```csharp theme={null}
using System.Text.Json.Nodes;
public class Event
{
public long Id { get; set; }
public JsonNode? Data { get; set; }
}
// In OnModelCreating:
entity.Property(e => e.Data).HasColumnType("Json");
```
La lecture et l’écriture du JSON s’effectuent via `SaveChanges` et `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 vous préférez des chaînes JSON brutes, mappez la propriété en `string` avec un type de colonne `Json` — le fournisseur applique automatiquement un `ValueConverter` :
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public string? Data { get; set; } // raw JSON string
}
entity.Property(e => e.Data).HasColumnType("Json");
```
* **Pas de traduction des chemins JSON** — `entity.Data["name"]` dans LINQ n’est pas converti en syntaxe SQL ClickHouse `data.name`. Filtrez sur des colonnes non JSON et examinez le JSON en mémoire.
* **Sémantique de NULL** — le type JSON de ClickHouse renvoie `{}` (objet vide) pour les valeurs NULL au lieu de SQL NULL.
* **Précision des entiers** — le JSON de ClickHouse stocke tous les entiers en `Int64`. Lors de la lecture via `JsonNode`, utilisez `GetValue()` plutôt que `GetValue()`.
#### Moteurs de table
Configurez les moteurs de table ClickHouse et les clauses propres à chaque moteur à l’aide de l’API fluide `ToTable(name, t => ...)`. Si aucun moteur n’est configuré, le fournisseur utilise par défaut `MergeTree`, avec `ORDER BY` déduit de la clé primaire de l’entité.
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("events", t => t
.HasMergeTreeEngine()
.WithOrderBy("UserId", "Timestamp")
.WithPartitionBy("toYYYYMM(Timestamp)")
.WithPrimaryKey("UserId")
.WithSettings("index_granularity = 8192"));
});
```
Familles de moteurs prises en charge :
| Moteur | Méthode Fluent | Remarques |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `MergeTree` | `HasMergeTreeEngine()` | Par défaut si rien n’est configuré |
| `ReplacingMergeTree` | `HasReplacingMergeTreeEngine("Version", "IsDeleted")` ou `HasReplacingMergeTreeEngine(e => e.Version)` | Colonnes Version / IsDeleted facultatives |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` ou `HasSummingMergeTreeEngine(e => new { … })` | Colonnes à additionner facultatives |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` ou `HasCollapsingMergeTreeEngine(e => e.Sign)` | La colonne `Sign` doit être de type `Int8` |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` ou `(e => e.Sign, e => e.Version)` | — |
| `GraphiteMergeTree` | `HasGraphiteMergeTreeEngine("config_section")` | — |
| `Log`, `TinyLog`, `StripeLog`, `Memory` | `HasLogEngine()`, `HasTinyLogEngine()`, `HasStripeLogEngine()`, `HasMemoryEngine()` | Pas de ORDER BY / PARTITION BY |
**Clauses du moteur :** `WithOrderBy`, `WithPartitionBy`, `WithPrimaryKey`, `WithSampleBy`, `WithTtl`, `WithSettings`. Elles s’appliquent toutes au builder de moteur renvoyé par `HasXxxEngine()`.
**Fonctionnalités au niveau des colonnes :** `HasCodec`, `HasTtl`, `HasComment`, `HasDefault` — toutes sont prises en compte dans les migrations.
**Index de saut de données** — via `HasIndex(...).HasSkippingIndexType(...)`:
```csharp theme={null}
modelBuilder.Entity()
.HasIndex(e => e.UserId)
.HasSkippingIndexType("minmax")
.HasGranularity(4);
// Index with parameters (e.g. bloom_filter, tokenbf_v1):
modelBuilder.Entity()
.HasIndex(e => e.Tag)
.HasSkippingIndexType("bloom_filter")
.HasSkippingIndexParams("0.01")
.HasGranularity(1);
```
Les index standard (non-skipping) sont ignorés sans avertissement, car ClickHouse n’a pas d’équivalent. Les index uniques provoquent une exception, car ClickHouse ne garantit pas l’unicité.
#### Migrations
Processus standard des migrations EF Core :
```bash theme={null}
dotnet ef migrations add InitialCreate
dotnet ef database update
```
Opérations prises en charge :
| Opération | Génère |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `CREATE TABLE` | Inclut la clause moteur, ORDER BY, PARTITION BY, SETTINGS, ainsi que les codecs/TTL/commentaires/valeurs par défaut des colonnes |
| `ALTER TABLE ADD COLUMN` | — |
| `ALTER TABLE DROP COLUMN` | — |
| `ALTER TABLE MODIFY COLUMN` | Gère les changements de type ainsi que l’ajout/la suppression d’annotations (CODEC, TTL, COMMENT, DEFAULT) |
| `ALTER TABLE RENAME COLUMN` | — |
| `RENAME TABLE` | — |
| `ALTER TABLE ADD INDEX` / `DROP INDEX` | Uniquement les index de saut de données |
| `CREATE DATABASE` / `DROP DATABASE` | Via `EnsureCreated` / `EnsureDeleted` et les migrations |
#### Limitations des migrations
| Fonctionnalité | Raison |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Clés étrangères | ClickHouse n’applique pas les clés étrangères. Les migrations rejettent `AddForeignKey` ; le validateur du modèle émet un avertissement lors de la génération du modèle. |
| Contraintes uniques / index uniques | ClickHouse n’applique pas l’unicité. Les index uniques génèrent une exception lors de la migration. |
| Valeurs générées par le serveur (auto-incrémentation / `IDENTITY`) | ClickHouse n’a pas d’équivalent. |
| Colonnes `Nested(…)` | Pas encore prises en charge comme type CLR mappé. |
| Entités possédées en JSON (`.ToJson()`) | Le mappage JSON structurel des entités possédées n’est pas encore implémenté. Utilisez plutôt `JsonNode` / `string` sur une colonne `Json` (voir [colonnes JSON](#ef-core-json)). |
Au-delà des migrations, le fournisseur ne prend pas encore en charge :
* **`UPDATE` / `DELETE`**
* **Transactions** : `BeginTransaction` est sans effet. Les transactions ACID ne sont pas prises en charge dans ClickHouse.
* **Traduction des requêtes avec chemin JSON** : `entity.Data["key"]` dans LINQ ne se traduit pas en syntaxe SQL ClickHouse `data.key`. Filtrez sur des colonnes non JSON et inspectez le JSON en mémoire.
## Limites
### Colonnes de type AggregateFunction
Les colonnes de type `AggregateFunction(...)` ne peuvent pas être interrogées ni faire l’objet d’une insertion directe.
Pour insérer :
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
Pour sélectionner :
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***