();
return new ClickHouseDataSource("Host=localhost", factory, "ClickHouse");
});
// サービス内
public class MyService
{
private readonly ClickHouseDataSource _dataSource;
public MyService(ClickHouseDataSource dataSource)
{
_dataSource = dataSource;
}
public async Task DoWorkAsync()
{
await using var connection = await _dataSource.OpenConnectionAsync();
// 接続を使用...
}
}
```
**本番環境のコードで `ClickHouseConnection` を直接作成しないでください**。直接インスタンス化するたびに、新しい HTTP クライアントと接続プールが作成されるため、高負荷時にソケットが枯渇するおそれがあります。
```csharp theme={null}
// これは避けてください - 毎回新しい接続プールが作成されます
using var conn = new ClickHouseConnection("Host=localhost");
await conn.OpenAsync();
```
代わりに、必ず `ClickHouseDataSource` を使用するか、単一の `ClickHouseClient` インスタンスを共有してください。
***
### ClickHouseCommand の使用
SQL を実行するコマンドを接続から作成します。
```csharp theme={null}
await using var connection = await dataSource.OpenConnectionAsync();
// SQLでコマンドを作成する
await using var command = connection.CreateCommand("SELECT * FROM my_table WHERE id = {id:Int64}");
command.AddParameter("id", 42L);
// 実行して結果を読み取る
await using var reader = await command.ExecuteReaderAsync();
while (reader.Read())
{
Console.WriteLine($"Name: {reader.GetString("name")}");
}
```
コマンド メソッド:
* `ExecuteNonQueryAsync()` - INSERT、UPDATE、DELETE、DDL ステートメントに使用します
* `ExecuteScalarAsync()` - 最初の行の最初のカラムを返します
* `ExecuteReaderAsync()` - 結果を反復処理するための `ClickHouseDataReader` を返します
***
### ClickHouseDataReader の使用
`ClickHouseDataReader` を使用すると、クエリ結果に型付きでアクセスできます。
```csharp theme={null}
await using var reader = await command.ExecuteReaderAsync();
while (reader.Read())
{
// カラムインデックスによるアクセス
var id = reader.GetInt64(0);
var name = reader.GetString(1);
// カラム名によるアクセス
var email = reader.GetString("email");
// 汎用アクセス
var timestamp = reader.GetFieldValue("created_at");
// nullチェック
if (!reader.IsDBNull("optional_field"))
{
var value = reader.GetString("optional_field");
}
}
```
## ベストプラクティス
### 接続の有効期間とプーリング
`ClickHouse.Driver` は内部で `System.Net.Http.HttpClient` を使用しています。`HttpClient` にはエンドポイントごとの接続プールがあります。そのため、次の点に注意してください。
* データベースセッションは、接続プールで管理される HTTP 接続を介して多重化されます。
* HTTP 接続はプールによって自動的に再利用されます。
* `ClickHouseClient` または `ClickHouseConnection` オブジェクトを破棄した後でも、接続が維持される場合があります。
**推奨パターン:**
| シナリオ | 推奨される方法 |
| -------------- | --------------------------------------------------------------------------------------- |
| 一般的な用途 | シングルトンの `ClickHouseClient` を使用する |
| ADO.NET / ORMs | `ClickHouseDataSource` を使用する (同じプールを共有する接続が作成されます) |
| DI 環境 | `IHttpClientFactory` を使用して、`ClickHouseClient` または `ClickHouseDataSource` をシングルトンとして登録する |
カスタムの `HttpClient` または `HttpClientFactory` を使用する場合は、半閉状態の接続によるエラーを避けるため、`PooledConnectionIdleTimeout` をサーバーの `keep_alive_timeout` より小さい値に設定してください。Cloud デプロイメントの既定の `keep_alive_timeout` は 10 秒です。
共有の `HttpClient` を使わずに、複数の `ClickHouseClient` や単独の `ClickHouseConnection` インスタンスを作成するのは避けてください。各インスタンスはそれぞれ独自の接続プールを作成します。
***
### DateTime の扱い
1. **可能な限り UTC を使用します。** タイムスタンプは `DateTime('UTC')` カラムとして保存し、コードでは `DateTimeKind.Utc` を使用します。これにより、タイムゾーンの曖昧さを排除できます。
2. **タイムゾーンを明示的に扱うには `DateTimeOffset` を使用します。** `DateTimeOffset` は常に特定の時点を表し、オフセット情報を含みます。
3. **SQL の型ヒントでタイムゾーンを指定します。** `Unspecified` の DateTime 値を持つパラメーターを使用して非 UTC カラムを対象とする場合は、SQL にタイムゾーンを含めます。
```csharp theme={null}
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("dt", myDateTime);
await client.ExecuteNonQueryAsync(
"INSERT INTO table (dt) VALUES ({dt:DateTime('Europe/Amsterdam')})",
parameters
);
```
***
### 非同期 INSERT
[非同期 INSERT](/ja/concepts/features/operations/insert/asyncinserts) では、バッチ化の責任がクライアントからサーバーに移ります。クライアント側でバッチ化する代わりに、サーバーが受信データをバッファに保持し、設定可能なしきい値に基づいてストレージに書き出します。これは、多数のエージェントが小さなペイロードを送信するオブザーバビリティのワークロードのような、高い同時実行性が求められるシナリオで有効です。
`CustomSettings` または接続文字列で非同期 INSERT を有効にします:
```csharp theme={null}
// CustomSettingsを使用する場合
var settings = new ClickHouseClientSettings("Host=localhost");
settings.CustomSettings["async_insert"] = 1;
settings.CustomSettings["wait_for_async_insert"] = 1; // 推奨: フラッシュの完了確認を待機する
// または接続文字列を使用する場合
// "Host=localhost;set_async_insert=1;set_wait_for_async_insert=1"
```
**2 つのモード** (`wait_for_async_insert` で制御) :
| Mode | Behavior | Use case |
| ------------------------- | ------------------------------------------------------ | ------------------ |
| `wait_for_async_insert=1` | データがディスクにフラッシュされた後に insert が完了します。エラーはクライアントに返されます。 | ほとんどのワークロードで**推奨** |
| `wait_for_async_insert=0` | データがバッファに格納された時点で、insert は即座に完了します。データが永続化される保証はありません。 | データ損失を許容できる場合のみ |
`wait_for_async_insert=0` では、エラーはフラッシュ時にのみ表面化するため、元の insert までさかのぼって特定できません。また、クライアント側でバックプレッシャーもかからないため、サーバーの過負荷を招くおそれがあります。
**主な設定:**
| Setting | Description |
| ------------------------------- | --------------------------- |
| `async_insert_max_data_size` | バッファがこのサイズ (バイト) に達したらフラッシュ |
| `async_insert_busy_timeout_ms` | このタイムアウト (ミリ秒) が経過したらフラッシュ |
| `async_insert_max_query_number` | この数のクエリが蓄積したらフラッシュ |
***
### セッション
セッションは、状態を保持するサーバー側の機能が必要な場合にのみ有効にしてください。例:
* 一時テーブル (`CREATE TEMPORARY TABLE`)
* 複数のステートメントにまたがってクエリコンテキストを維持する
* セッションレベルの設定 (`SET max_threads = 4`)
セッションを有効にすると、同じセッションの同時使用を防ぐため、リクエストは直列化されます。そのため、セッション状態を必要としないワークロードではオーバーヘッドが発生します。
```csharp theme={null}
var settings = new ClickHouseClientSettings
{
Host = "localhost",
UseSession = true,
SessionId = "my-session", // 省略可能 -- 指定しない場合は自動生成されます
};
using var client = new ClickHouseClient(settings);
await client.ExecuteNonQueryAsync("CREATE TEMPORARY TABLE temp_ids (id UInt64)");
await client.ExecuteNonQueryAsync("INSERT INTO temp_ids VALUES (1), (2), (3)");
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM users WHERE id IN (SELECT id FROM temp_ids)"
);
```
**ADO.NET を使用する場合 (ORM との互換性のため) :**
```csharp theme={null}
var settings = new ClickHouseClientSettings
{
Host = "localhost",
UseSession = true,
SessionId = "my-session",
};
var dataSource = new ClickHouseDataSource(settings);
await using var connection = await dataSource.OpenConnectionAsync();
await using var cmd1 = connection.CreateCommand("CREATE TEMPORARY TABLE temp_ids (id UInt64)");
await cmd1.ExecuteNonQueryAsync();
await using var cmd2 = connection.CreateCommand("INSERT INTO temp_ids VALUES (1), (2), (3)");
await cmd2.ExecuteNonQueryAsync();
await using var cmd3 = connection.CreateCommand("SELECT * FROM users WHERE id IN (SELECT id FROM temp_ids)");
await using var reader = await cmd3.ExecuteReaderAsync();
```
## サポートされているデータ型
`ClickHouse.Driver` は、ClickHouse のすべてのデータ型をサポートしています。以下の表は、データベースからデータを読み取る際の ClickHouse の型とネイティブの .NET 型の対応関係を示しています。
### 型マッピング: ClickHouseから読み取る場合
#### 整数型
| ClickHouse型 | .NET型 |
| ----------- | ------------ |
| Int8 | `sbyte` |
| UInt8 | `byte` |
| Int16 | `short` |
| UInt16 | `ushort` |
| Int32 | `int` |
| UInt32 | `uint` |
| Int64 | `long` |
| UInt64 | `ulong` |
| Int128 | `BigInteger` |
| UInt128 | `BigInteger` |
| Int256 | `BigInteger` |
| UInt256 | `BigInteger` |
***
#### 浮動小数点型
| ClickHouse型 | .NET型 |
| ----------- | -------- |
| Float32 | `float` |
| Float64 | `double` |
| BFloat16 | `float` |
***
#### Decimal 型
| ClickHouse 型 | .NET 型 |
| ------------- | ------------------------------- |
| Decimal(P, S) | `decimal` / `ClickHouseDecimal` |
| Decimal32(S) | `decimal` / `ClickHouseDecimal` |
| Decimal64(S) | `decimal` / `ClickHouseDecimal` |
| Decimal128(S) | `decimal` / `ClickHouseDecimal` |
| Decimal256(S) | `decimal` / `ClickHouseDecimal` |
Decimal 型の変換は UseCustomDecimals 設定で制御されます。
***
#### Boolean 型
| ClickHouse 型 | .NET 型 |
| ------------ | ------ |
| Bool | `bool` |
***
#### String 型
| ClickHouse 型 | .NET 型 |
| -------------- | -------- |
| String | `string` |
| FixedString(N) | `string` |
デフォルトでは、`String` と `FixedString(N)` の両方のカラムは `string` として返されます。代わりに `byte[]` として読み取るには、接続文字列で `ReadStringsAsByteArrays=true` を設定します。これは、有効な UTF-8 でない可能性があるバイナリデータを保存する場合に便利です。
***
#### 日付と時刻の型
| ClickHouse 型 | .NET 型 |
| ------------ | ---------- |
| Date | `DateTime` |
| Date32 | `DateTime` |
| DateTime | `DateTime` |
| DateTime32 | `DateTime` |
| DateTime64 | `DateTime` |
| Time | `TimeSpan` |
| Time64 | `TimeSpan` |
ClickHouse では、`DateTime` と `DateTime64` の値は内部的に Unix timestamp (epoch からの秒、またはその下位単位) として保存されます。保存は常に UTC ですが、カラムにはタイムゾーンを関連付けることができ、これによって値の表示方法や解釈方法が変わります。
`DateTime` の値を読み取る際、`DateTime.Kind` プロパティはカラムのタイムゾーンに基づいて設定されます。
| カラム定義 | 返される `DateTime.Kind` | 補足 |
| ------------------------------ | -------------------- | ------------- |
| `DateTime('UTC')` | `Utc` | UTC タイムゾーンを明示 |
| `DateTime('Europe/Amsterdam')` | `Unspecified` | オフセットが適用される |
| `DateTime` | `Unspecified` | ローカル時刻をそのまま保持 |
UTC 以外のカラムでは、返される `DateTime` はそのタイムゾーンでのローカル時刻を表します。そのタイムゾーンに対する正しいオフセットを持つ `DateTimeOffset` を取得するには、`ClickHouseDataReader.GetDateTimeOffset()` を使用してください。
```csharp theme={null}
var reader = (ClickHouseDataReader)await connection.ExecuteReaderAsync(
"SELECT toDateTime('2024-06-15 14:30:00', 'Europe/Amsterdam')");
reader.Read();
var dt = reader.GetDateTime(0); // 2024-06-15 14:30:00, Kind=Unspecified（未指定）
var dto = reader.GetDateTimeOffset(0); // 2024-06-15 14:30:00 +02:00 (CEST)
```
明示的なタイムゾーンを **持たない** カラム (つまり `DateTime('Europe/Amsterdam')` ではなく `DateTime`) については、ドライバーは `Kind=Unspecified` の `DateTime` を返します。これにより、タイムゾーンについて何も仮定せず、保存されている時刻の値をそのまま正確に保持できます。
明示的なタイムゾーンを持たないカラムでタイムゾーンを考慮した動作が必要な場合は、次のいずれかを行ってください。
1. カラム定義で明示的なタイムゾーンを使用する: `DateTime('UTC')` または `DateTime('Europe/Amsterdam')`
2. 読み取り後に自分でタイムゾーンを適用する。
***
#### JSON 型
| ClickHouse Type | .NET Type | Notes |
| --------------- | ------------ | ----------------------------- |
| Json | `JsonObject` | デフォルト (`JsonReadMode=Binary`) |
| Json | `string` | `JsonReadMode=String` の場合 |
JSON カラムの戻り値の型は、`JsonReadMode` 設定で制御されます。
* **`Binary` (デフォルト)**: `System.Text.Json.Nodes.JsonObject` を返します。JSON データを構造化された形で扱えますが、特殊な ClickHouse 型 (IP アドレス、UUID、高精度の Decimal 値など) は、JSON 構造内では文字列表現に変換されます。
* **`String`**: 生の JSON を `string` として返します。ClickHouse の JSON 表現をそのまま保持できるため、JSON をパースせずにそのまま受け渡したい場合や、デシリアライゼーションを自分で処理したい場合に便利です。
```csharp theme={null}
// 設定でStringモードを構成する
var settings = new ClickHouseClientSettings("Host=localhost")
{
JsonReadMode = JsonReadMode.String
};
// または接続文字列で指定する
// "Host=localhost;JsonReadMode=String"
```
***
#### その他の型
| ClickHouse 型 | .NET 型 |
| ----------------------- | ----------------------------------- |
| UUID | `Guid` |
| IPv4 | `IPAddress` |
| IPv6 | `IPAddress` |
| Nothing | `DBNull` |
| Dynamic | 注を参照 |
| Array(T) | `T[]` |
| Tuple(T1, T2, ...) | `Tuple` / `LargeTuple` |
| Map(K, V) | `Dictionary` |
| Nullable(T) | `T?` |
| Enum8 | `string` |
| Enum16 | `string` |
| LowCardinality(T) | T と同じ |
| SimpleAggregateFunction | 基底となる型と同じ |
| Nested(...) | `Tuple[]` |
| Variant(T1, T2, ...) | 注を参照 |
| QBit(T, dimension) | `T[]` |
Dynamic 型と Variant 型は、各行で実際に使用されている基底型に対応する型に変換されます。
***
#### ジオメトリ型
| ClickHouse 型 | .NET 型 |
| --------------- | ------------------------- |
| Point | `Tuple` |
| Ring | `Tuple[]` |
| LineString | `Tuple[]` |
| Polygon | `Ring[]` |
| MultiLineString | `LineString[]` |
| MultiPolygon | `Polygon[]` |
| Geometry | 注を参照 |
Geometry 型は、任意のジオメトリ型を保持できる Variant 型で、対応する型に変換されます。
***
### 型マッピング: ClickHouse への書き込み
データの挿入時に、ドライバーは .NET 型を対応する ClickHouse 型に変換します。以下の表は、各 ClickHouse カラム型で受け入れ可能な .NET 型を示しています。
#### 整数型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| ------------ | ------------------------------------------------------------------------------------------------------- | -- |
| Int8 | `sbyte`、および `Convert.ToSByte()` と互換性のある任意の型 | |
| UInt8 | `byte`、および `Convert.ToByte()` と互換性のある任意の型 | |
| Int16 | `short`、および `Convert.ToInt16()` と互換性のある任意の型 | |
| UInt16 | `ushort`、および `Convert.ToUInt16()` と互換性のある任意の型 | |
| Int32 | `int`、および `Convert.ToInt32()` と互換性のある任意の型 | |
| UInt32 | `uint`、および `Convert.ToUInt32()` と互換性のある任意の型 | |
| Int64 | `long`、および `Convert.ToInt64()` と互換性のある任意の型 | |
| UInt64 | `ulong`、および `Convert.ToUInt64()` と互換性のある任意の型 | |
| Int128 | `BigInteger`、`decimal`、`double`、`float`、`int`、`uint`、`long`、`ulong`、および `Convert.ToInt64()` と互換性のある任意の型 | |
| UInt128 | `BigInteger`、`decimal`、`double`、`float`、`int`、`uint`、`long`、`ulong`、および `Convert.ToInt64()` と互換性のある任意の型 | |
| Int256 | `BigInteger`、`decimal`、`double`、`float`、`int`、`uint`、`long`、`ulong`、および `Convert.ToInt64()` と互換性のある任意の型 | |
| UInt256 | `BigInteger`、`decimal`、`double`、`float`、`int`、`uint`、`long`、`ulong`、および `Convert.ToInt64()` と互換性のある任意の型 | |
***
#### 浮動小数点型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 備考 |
| ------------ | --------------------------------------------- | -------------------------- |
| Float32 | `float`、および `Convert.ToSingle()` と互換性のある任意の型 | |
| Float64 | `double`、および `Convert.ToDouble()` と互換性のある任意の型 | |
| BFloat16 | `float`、および `Convert.ToSingle()` と互換性のある任意の型 | 16 ビットの bfloat 形式に切り詰められます |
***
#### ブール型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 備考 |
| ------------ | -------------- | -- |
| Bool | `bool` | |
***
#### 文字列型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| -------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| String | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | バイナリ型はそのまま書き込まれます。ストリームはシーク可能なものと不可能なものがあります |
| FixedString(N) | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | String は UTF-8 でエンコードされたうえでパディングされます。バイナリ型は厳密に N バイトである必要があります |
***
#### 日付と時刻の型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| ------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Date | `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime 型 | Unix 日数として `UInt16` に変換されます |
| Date32 | `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime 型 | Unix 日数として `Int32` に変換されます |
| DateTime | `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime 型 | 詳細は以下を参照 |
| DateTime32 | `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime 型 | `DateTime` と同じ |
| DateTime64 | `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime 型 | 精度はスケールパラメータに基づきます |
| Time | `TimeSpan`, `int` | ±999:59:59 に丸められます。`int` は秒として扱われます |
| Time64 | `TimeSpan`, `decimal`, `double`, `float`, `int`, `long`, `string` | `string` は `[-]HHH:MM:SS[.fraction]` として解析され、±999:59:59.999999999 に丸められます |
ドライバーは値の書き込み時に `DateTime.Kind` を考慮します。
| DateTime.Kind | HTTP パラメータ | バルクコピー |
| ------------- | ------------------------------------------ | ---------------------------- |
| Utc | 時点は保持されます | 時点は保持されます |
| Local | 時点は保持されます | 時点は保持されます |
| Unspecified | パラメータ型の timezone の壁時計時刻として扱われます (既定では UTC) | カラムの timezone の壁時計時刻として扱われます |
`DateTimeOffset` の値では、常に正確な時点が保持されます。
**例: UTC DateTime (時点は保持される) **
```csharp theme={null}
var utcTime = new DateTime(2024, 1, 15, 12, 0, 0, DateTimeKind.Utc);
// 12:00 UTC として保存
// DateTime('Europe/Amsterdam') カラムから読み取り: 13:00 (UTC+1)
// DateTime('UTC') カラムから読み取り: 12:00 UTC
```
**例: 未指定の DateTime (時計上の時刻) **
```csharp theme={null}
var wallClock = new DateTime(2024, 1, 15, 14, 30, 0, DateTimeKind.Unspecified);
// DateTime('Europe/Amsterdam') カラムへの書き込み: アムステルダム時刻の 14:30 として保存
// DateTime('Europe/Amsterdam') カラムからの読み取り: 14:30
```
**推奨事項:** 最もシンプルで予測しやすい動作にするため、すべての DateTime 操作で `DateTimeKind.Utc` または `DateTimeOffset` を使用してください。これにより、サーバーのタイムゾーン、クライアントのタイムゾーン、またはカラムのタイムゾーンに関係なく、コードが常に一貫して動作します。
#### HTTP パラメータと Bulk Copy の違い
`Unspecified` の DateTime 値を書き込む際、HTTP パラメータのバインドと Bulk Copy には重要な違いがあります。
**Bulk Copy** は対象カラムのタイムゾーンを認識しており、そのタイムゾーンで `Unspecified` の値を正しく解釈します。
**HTTP Parameters** はカラムのタイムゾーンを自動的には認識しません。SQL の型ヒントでそのタイムゾーンを指定する必要があります。
```csharp theme={null}
// 正しい例: SQLの型ヒントにタイムゾーンを指定 - 型は自動的に抽出される
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime('Europe/Amsterdam')})";
command.AddParameter("dt", myDateTime);
// 誤った例: タイムゾーンヒントなしの場合、UTCとして解釈される
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime})";
command.AddParameter("dt", myDateTime);
// 文字列値 "2024-01-15 14:30:00" はアムステルダム時間ではなくUTCとして解釈される！
```
| `DateTime.Kind` | 対象カラム | HTTP パラメータ (tz ヒントあり) | HTTP パラメータ (tz ヒントなし) | Bulk Copy |
| --------------- | ---------------- | --------------------- | --------------------- | ---------------- |
| `Utc` | UTC | 時点が保持される | 時点が保持される | 時点が保持される |
| `Utc` | Europe/Amsterdam | 時点が保持される | 時点が保持される | 時点が保持される |
| `Local` | 任意 | 時点が保持される | 時点が保持される | 時点が保持される |
| `Unspecified` | UTC | UTC として扱われる | UTC として扱われる | UTC として扱われる |
| `Unspecified` | Europe/Amsterdam | アムステルダム時間として扱われる | **UTC として扱われる** | アムステルダム時間として扱われる |
***
#### Decimal 型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| ------------ | ------------------------------------------------------------------- | ----------------------------------- |
| Decimal(P,S) | `decimal`、`ClickHouseDecimal`、および `Convert.ToDecimal()` と互換性のある任意の型 | 精度を超えると `OverflowException` をスローします |
| Decimal32 | `decimal`、`ClickHouseDecimal`、および `Convert.ToDecimal()` と互換性のある任意の型 | 最大精度 9 |
| Decimal64 | `decimal`、`ClickHouseDecimal`、および `Convert.ToDecimal()` と互換性のある任意の型 | 最大精度 18 |
| Decimal128 | `decimal`、`ClickHouseDecimal`、および `Convert.ToDecimal()` と互換性のある任意の型 | 最大精度 38 |
| Decimal256 | `decimal`、`ClickHouseDecimal`、および `Convert.ToDecimal()` と互換性のある任意の型 | 最大精度 76 |
***
#### JSON 型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| ------------ | ------------------------------------------ | ---------------------------- |
| Json | `string`、`JsonObject`、`JsonNode`、任意のオブジェクト | 動作は `JsonWriteMode` 設定に依存します |
JSON の書き込み時の動作は、`JsonWriteMode` 設定で制御されます。
| 入力型 | `JsonWriteMode.String` (デフォルト) | `JsonWriteMode.Binary` |
| -------------------- | ---------------------------------------- | ---------------------------------------------- |
| `string` | そのまま渡されます | `ArgumentException` をスローします |
| `JsonObject` | `ToJsonString()` でシリアライズされます | `ArgumentException` をスローします |
| `JsonNode` | `ToJsonString()` でシリアライズされます | `ArgumentException` をスローします |
| 登録済み POCO | `JsonSerializer.Serialize()` でシリアライズされます | 型ヒント付きのバイナリエンコーディング。カスタムパス属性もサポート |
| 未登録の POCO / 匿名オブジェクト | `JsonSerializer.Serialize()` でシリアライズされます | `ClickHouseJsonSerializationException` をスローします |
* **`String` (デフォルト)**: `string`、`JsonObject`、`JsonNode`、または任意のオブジェクトを受け付けます。すべての入力は `System.Text.Json.JsonSerializer` でシリアライズされ、サーバー側でパースするために JSON 文字列として送信されます。これは最も柔軟なモードで、型登録なしで動作します。
* **`Binary`**: 登録済みの POCO 型のみを受け付けます。データはクライアント側で、完全な型ヒントのサポート付きで ClickHouse のバイナリ JSON フォーマットに変換されます。使用する前に `connection.RegisterJsonSerializationType()` を呼び出す必要があります。このモードで `string` または `JsonNode` の値を書き込むと、`ArgumentException` がスローされます。
```csharp theme={null}
// デフォルトのStringモードはあらゆる入力で動作
await client.InsertBinaryAsync(
"my_table",
new[] { "id", "data" },
new[] { new object[] { 1u, new { name = "test", value = 42 } } }
);
// Binaryモードは明示的なオプトインと型の登録が必要
var settings = new ClickHouseClientSettings("Host=localhost")
{
JsonWriteMode = JsonWriteMode.Binary
};
using var client = new ClickHouseClient(settings);
client.RegisterJsonSerializationType();
```
##### 型付き JSON カラム
JSON カラムに型ヒント (例: `JSON(id UInt64, price Decimal128(2))`) がある場合、ドライバーはそれらのヒントを使って、値を型情報を完全に保ったままシリアライズします。これにより、`UInt64`、`Decimal`、`UUID`、`DateTime64` など、汎用的な JSON としてシリアライズすると精度が失われる可能性のある型でも、精度を保持できます。
##### POCO のシリアライゼーション
POCO は、`JsonWriteMode` に応じて 2 つの方法で JSON カラムに書き込めます。
**String mode (default)**: POCO は `System.Text.Json.JsonSerializer` によってシリアライズされます。型の登録は不要です。最もシンプルな方法で、匿名オブジェクトでも使用できます。
**Binary mode**: POCO は、型ヒントを完全にサポートするドライバーのバイナリ JSON フォーマットを使用してシリアライズされます。使用前に `connection.RegisterJsonSerializationType()` で型を登録する必要があります。このモードでは、属性を使ったカスタムパスマッピングをサポートします。
* **`[ClickHouseJsonPath("path")]`**: プロパティをカスタム JSON パスにマッピングします。ネストされた structure や、プロパティ名が目的の JSON キーと異なる場合に便利です。**Binary mode でのみ機能します。**
* **`[ClickHouseJsonIgnore]`**: プロパティをシリアライゼーションの対象から除外します。**Binary mode でのみ機能します。**
```sql theme={null}
CREATE TABLE events (
id UInt32,
data JSON(`user.id` Int64, `user.name` String, Timestamp DateTime64(3))
) ENGINE = MergeTree() ORDER BY id
```
```csharp theme={null}
using ClickHouse.Driver.Json;
public class UserEvent
{
[ClickHouseJsonPath("user.id")]
public long UserId { get; set; }
[ClickHouseJsonPath("user.name")]
public string UserName { get; set; }
public DateTime Timestamp { get; set; }
[ClickHouseJsonIgnore]
public string InternalData { get; set; } // シリアライズされない
}
// バイナリモードの場合: 型を登録してバイナリモードを有効にする
var settings = new ClickHouseClientSettings("Host=localhost") { JsonWriteMode = JsonWriteMode.Binary };
using var client = new ClickHouseClient(settings);
client.RegisterJsonSerializationType();
// POCOを挿入 - カスタムパス属性によりネスト構造を持つJSONにシリアライズされる
await client.InsertBinaryAsync(
"events",
new[] { "id", "data" },
new[] { new object[] { 1u, new UserEvent { UserId = 123, UserName = "Alice", Timestamp = DateTime.UtcNow } } }
);
// 生成されるJSON: {"user": {"id": 123, "name": "Alice"}, "Timestamp": "2024-01-15T..."}
```
プロパティ名とカラムの型ヒントの照合では、大文字と小文字が区別されます。プロパティ `UserId` は、`userid` ではなく、`UserId` と定義されたヒントにのみ一致します。これは、`userName` と `UserName` のようなパスを別個のフィールドとして共存させられる ClickHouse の動作と一致しています。
**制限事項 (Binary mode のみ) :**
* POCO 型は、シリアライズする前に `connection.RegisterJsonSerializationType()` を使用してコネクションに登録しておく必要があります。未登録の型をシリアライズしようとすると、`ClickHouseJsonSerializationException` がスローされます。
* Dictionary および配列/リストのプロパティを正しくシリアライズするには、カラム定義に型ヒントが必要です。ヒントがない場合は、代わりに String mode を使用してください。
* POCO プロパティの null 値は、カラム定義内のパスに `Nullable(T)` 型ヒントがある場合にのみ書き込まれます。ClickHouse では動的 JSON パス内で `Nullable` 型は使用できないため、ヒントのない null プロパティはスキップされます。
* `ClickHouseJsonPath` 属性と `ClickHouseJsonIgnore` 属性は String mode では無視されます (有効なのは Binary mode のみです) 。
***
#### その他の型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| ----------------------- | --------------------------------- | ------------------------------------------------------- |
| UUID | `Guid`, `string` | `string` は Guid としてパースされます |
| IPv4 | `IPAddress`, `string` | IPv4 である必要があります。`string` は `IPAddress.Parse()` でパースされます |
| IPv6 | `IPAddress`, `string` | IPv6 である必要があります。`string` は `IPAddress.Parse()` でパースされます |
| Nothing | Any | 何も書き込みません (no-op) |
| Dynamic | — | **未サポート** (`NotImplementedException` をスローします) |
| Array(T) | `IList`, `null` | `null` は空配列として書き込まれます |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | 要素数はタプルの要素数と一致する必要があります |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull`, または T で受け入れ可能な型 | 値の前に null フラグのバイトを書き込みます |
| Enum8 | `string`, `sbyte`, 数値型 | `string` は enum 辞書で参照されます |
| Enum16 | `string`, `short`, 数値型 | `string` は enum 辞書で参照されます |
| LowCardinality(T) | T で受け入れ可能な型 | 基になる型に委譲します |
| SimpleAggregateFunction | 基になる型で受け入れ可能な型 | 基になる型に委譲します |
| Nested(...) | タプルの `IList` | 要素数はフィールド数と一致する必要があります |
| Variant(T1, T2, ...) | T1, T2, ... のいずれかに一致する値 | 一致する型がない場合は `ArgumentException` をスローします |
| QBit(T, dim) | `IList` | Array に委譲します。次元はメタデータとしてのみ使用されます |
***
#### ジオメトリ型
| ClickHouse 型 | 受け入れ可能な .NET 型 | 注記 |
| --------------- | ------------------------------------------------ | --------------------- |
| Point | `System.Drawing.Point`, `ITuple`, `IList` (2 要素) | |
| Ring | Point の `IList` | |
| LineString | Point の `IList` | |
| Polygon | Ring の `IList` | |
| MultiLineString | LineString の `IList` | |
| MultiPolygon | Polygon の `IList` | |
| Geometry | 上記のいずれかのジオメトリ型 | すべてのジオメトリ型を含む Variant |
***
#### 書き込みではサポートされていません
| ClickHouse 型 | 備考 |
| ----------------- | ------------------------------------- |
| Dynamic | `NotImplementedException` がスローされます |
| AggregateFunction | `AggregateFunctionException` がスローされます |
***
### ネスト型の扱い
ClickHouse のネスト型 (`Nested(...)`) は、配列として読み書きできます。
```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 }
);
```
## ログと診断
ClickHouse の .NET クライアントは、`Microsoft.Extensions.Logging` の抽象化レイヤーと統合されており、軽量で必要に応じて有効化できるログ機能を提供します。有効にすると、ドライバーは接続ライフサイクル イベント、コマンド実行、トランスポート処理、バルク挿入操作に関する構造化メッセージを出力します。ログ機能は完全に任意であり、ロガーを設定していないアプリケーションも追加のオーバーヘッドなしでそのまま動作し続けます。
### クイックスタート
```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);
```
#### appsettings.json を使用する
.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);
```
#### インメモリ構成を使用する
コード内で、カテゴリ別にログ出力の詳細度を設定することもできます。
```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);
```
### カテゴリと出力元
ドライバーは専用のカテゴリを使用しているため、コンポーネントごとにログレベルを細かく調整できます。
| カテゴリ | ソース | 主な内容 |
| ------------------------------ | ---------------------- | ---------------------------------------------------------- |
| `ClickHouse.Driver.Connection` | `ClickHouseConnection` | 接続のライフサイクル、HTTP クライアント ファクトリーの選択、接続のオープン/クローズ、セッション管理。 |
| `ClickHouse.Driver.Command` | `ClickHouseCommand` | クエリ実行の開始/完了、所要時間、クエリ ID、サーバー統計情報、エラーの詳細。 |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | 低レベルの HTTP ストリーミング リクエスト、圧縮フラグ、レスポンスのステータスコード、トランスポート エラー。 |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | バイナリ insert、クエリ、その他の操作 |
| `ClickHouse.Driver.NetTrace` | `TraceHelper` | ネットワークトレース (デバッグモードが有効な場合のみ) |
#### 例: 接続の問題を診断する
```json theme={null}
{
"Logging": {
"LogLevel": {
"ClickHouse.Driver.Connection": "Trace",
"ClickHouse.Driver.Transport": "Trace"
}
}
}
```
以下の内容がログに記録されます。
* HTTP クライアント ファクトリの選択 (既定のプールまたは単一接続)
* HTTP ハンドラーの設定 (SocketsHttpHandler または HttpClientHandler)
* 接続プールの設定 (MaxConnectionsPerServer、PooledConnectionLifetime など)
* タイムアウトの設定 (ConnectTimeout、Expect100ContinueTimeout など)
* SSL/TLS の設定
* 接続のオープン/クローズ イベント
* セッション ID の追跡
### デバッグモード: ネットワークトレースと診断
ネットワーク関連の問題の診断に役立てるため、ドライバーライブラリには .NET のネットワーク内部処理の低レベルトレースを有効にするヘルパーが含まれています。これを有効にするには、レベルを Trace に設定した LoggerFactory を渡し、EnableDebugMode を true に設定する必要があります (または `ClickHouse.Driver.Diagnostic.TraceHelper` クラスを使って手動で有効にします) 。イベントは `ClickHouse.Driver.NetTrace` カテゴリにログ出力されます。警告: これにより非常に大量の logs が生成され、パフォーマンスに影響します。本番環境でデバッグモードを有効にすることは推奨されません。
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // ネットワークイベントを表示するにはTraceレベルが必要
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // 低レベルのネットワークトレースを有効にする
};
```
## OpenTelemetry
このドライバーは、.NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing) API を通じて、OpenTelemetry の分散トレーシングをネイティブにサポートしています。有効にすると、ドライバーはデータベース操作に対するスパンを出力し、それらを Jaeger や ClickHouse 自体 ([OpenTelemetry Collector](/ja/guides/use-cases/observability/build-your-own/integrating-opentelemetry) 経由) などのオブザーバビリティバックエンドにエクスポートできます。
### トレーシングを有効にする
ASP.NET Core アプリケーションでは、ClickHouse ドライバーの `ActivitySource` を OpenTelemetry の設定に追加します。
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // ClickHouse ドライバーのスパンを購読する
.AddAspNetCoreInstrumentation()
.AddOtlpExporter()); // または AddJaegerExporter() など
```
コンソールアプリケーション、テスト、または手動セットアップの場合:
```csharp theme={null}
using OpenTelemetry;
using OpenTelemetry.Trace;
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName)
.AddConsoleExporter()
.Build();
```
### スパン属性
各スパンには、標準的なOpenTelemetryのデータベース属性に加え、デバッグに利用できるClickHouse固有のクエリ統計情報が含まれます。
| 属性 | 説明 |
| ----------------------------- | ----------------- |
| `db.system` | 常に `"clickhouse"` |
| `db.name` | データベース名 |
| `db.user` | ユーザー名 |
| `db.statement` | SQLクエリ (有効な場合) |
| `db.clickhouse.read_rows` | クエリで読み取られた行数 |
| `db.clickhouse.read_bytes` | クエリで読み取られたバイト数 |
| `db.clickhouse.written_rows` | クエリで書き込まれた行数 |
| `db.clickhouse.written_bytes` | クエリで書き込まれたバイト数 |
| `db.clickhouse.elapsed_ns` | サーバー側の実行時間 (ナノ秒) |
### 設定オプション
`ClickHouseDiagnosticsOptions` を使用して、トレーシングの動作を制御します。
```csharp theme={null}
using ClickHouse.Driver.Diagnostic;
// スパンにSQLステートメントを含める（デフォルト: セキュリティのためfalse）
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// 長いSQLステートメントを切り詰める（デフォルト: 1000文字）
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
`IncludeSqlInActivityTags` を有効にすると、トレースに機密データが含まれる可能性があります。本番環境での使用には注意してください。
## TLS 設定
HTTPS 経由で ClickHouse に接続する場合、TLS/SSL の挙動はいくつかの方法で設定できます。
### カスタム証明書の検証
本番環境でカスタムの証明書検証ロジックが必要な場合は、`ServerCertificateCustomValidationCallback` ハンドラーを構成した独自の `HttpClient` を指定します。
```csharp theme={null}
using System.Net;
using System.Net.Security;
using ClickHouse.Driver;
var handler = new HttpClientHandler
{
// 圧縮が有効な場合に必要（デフォルトで有効）
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate,
ServerCertificateCustomValidationCallback = (message, cert, chain, sslPolicyErrors) =>
{
// 例: 特定の証明書サムプリントを許可する
if (cert?.Thumbprint == "YOUR_EXPECTED_THUMBPRINT")
return true;
// 例: 特定の発行者からの証明書を許可する
if (cert?.Issuer.Contains("YourOrganization") == true)
return true;
// デフォルト: 標準の検証を使用
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);
```
カスタム HttpClient を指定する際の注意事項
* **自動圧縮解除**: 圧縮が無効になっていない場合は、`AutomaticDecompression` を有効にする必要があります (圧縮はデフォルトで有効です) 。
* **アイドルタイムアウト**: ハーフオープン接続による接続エラーを避けるため、`PooledConnectionIdleTimeout` はサーバーの `keep_alive_timeout` (ClickHouse Cloud では 10 秒) より短く設定してください。
## ORM サポート
ORM では ADO.NET API (`ClickHouseConnection`) が必要です。接続のライフサイクルを適切に管理するため、`ClickHouseDataSource` から接続を作成してください。
```csharp theme={null}
// DataSourceをシングルトンとして登録する
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default");
// ORM用のコネクションを作成する
await using var connection = await dataSource.OpenConnectionAsync();
// コネクションをORMに渡す...
```
### Dapper
`ClickHouse.Driver` は Dapper に対応しています。ドライバーは、Dapper の `@parameter` 構文を ClickHouse のネイティブな `{parameter:Type}` 構文に自動変換し、型は .NET の値から推論されます。
適切に connection のライフタイムを管理するには、`ClickHouseDataSource` を使用します。
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // DIにシングルトンとして登録
using var connection = dataSource.CreateConnection();
```
#### パラメーターの受け渡し形式
標準的な Dapper のパラメーター指定方法をすべてサポートしています。
**匿名オブジェクト:**
```csharp theme={null}
await connection.ExecuteAsync(
"INSERT INTO users (id, name, balance) VALUES (@Id, @Name, @Balance)",
new { Id = 1, Name = "alice", Balance = 3.14 });
```
**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);
```
**Dictionary:**
```csharp theme={null}
var parameters = new Dictionary { { "Id", 2 } };
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", parameters);
```
**`DynamicParameters` (ディクショナリまたは匿名オブジェクトから) :**
```csharp theme={null}
var dynParams = new DynamicParameters(new { Id = 1 });
// または: new DynamicParameters(new Dictionary { { "Id", 1 } });
var rows = await connection.QueryAsync(
"SELECT id, name FROM users WHERE id = @Id", dynParams);
```
#### POCO へのクエリ
Dapper は、カラム名に基づいてプロパティにマッピングします (大文字と小文字を区別しません) 。
```csharp theme={null}
class User
{
public int Id { get; set; }
public string Name { get; set; }
public double Balance { get; set; }
}
// テーブルから
var users = (await connection.QueryAsync("SELECT id, name, balance FROM users")).ToList();
// リテラルから
var row = (await connection.QueryAsync("SELECT 1 as id, 'hello' as name, 2.5 as balance")).Single();
```
#### ClickHouseネイティブのパラメーター構文
型を明示的に制御する必要がある場合は、パラメーター値に `Dictionary` を使用し、SQL 内で ClickHouse の `{param:Type}` 構文を直接使用してください。同じパラメーターに対して `@param` 構文と `{param:Type}` 構文を併用しないでください。
```csharp theme={null}
var parameters = new Dictionary { { "value", 42 } };
var result = await connection.QueryAsync("SELECT {value:Int32}", parameters);
```
#### WHERE IN
**DapperのネイティブなIN展開が機能します：**
```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 はこれを `WHERE id IN (@Ids1, @Ids2, @Ids3)` に書き換え、ドライバーが展開された各パラメーターをそれぞれ変換します。
**Array パラメーターを使った ClickHouse の `has()` も動作します:**
```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);
```
#### カスタム型ハンドラー
`ITuple`、`BigInteger`、`ClickHouseDecimal` など、一部の ClickHouse の型では、起動時にハンドラーを登録する必要があります。
```csharp theme={null}
// ClickHouseDecimal（Decimal64/128/256カラム用）
SqlMapper.AddTypeHandler(new ClickHouseDecimalHandler());
// BigInteger（Int128/Int256/UInt128/UInt256カラム用）
SqlMapper.AddTypeHandler(new BigIntegerHandler());
// IPAddress（IPv4/IPv6カラム用）
SqlMapper.AddTypeHandler(new IpAddressHandler());
```
型ハンドラーの実装例は、[Dapper の例](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/ORM/ORM_001_Dapper.cs)を参照してください。
#### Dapper.Contrib
`GetAll()` と `Get(id)` は動作します。`Insert()` は動作しません。これは SQL Server の構文 (`SCOPE_IDENTITY`、`[]`) を生成するためです。代わりに、ClickHouseClient のネイティブな `InsertBinaryAsync` メソッドを使用することを推奨します。
```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);
```
プロパティ名は ClickHouse のカラム名と完全に一致している必要があります (大文字と小文字を区別します) 。
#### 制限事項
| 項目 | ステータス | 詳細 |
| ---------------------------- | ----- | --------------------------------------------------------------- |
| **結果**としての Tuple | 動作します | `SqlMapper.TypeHandler` の登録が必要です |
| **パラメーター**としての Tuple | 未対応 | Dapper は `ITuple`/`Tuple<>` を `DbParameter` の値としてシリアル化できません |
| パラメーターとしてのネストされた型 | 未対応 | 同じ理由で、Dapper は複雑な型をパラメーター値として受け付けません |
| パラメーターとしての Geo 型 | 未対応 | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | 未対応 | SQL Server 固有の構文を生成します |
| `Nothing` 型 | 未対応 | 意味のある .NET での表現がありません |
### Linq2db
このドライバーは、.NET 向けの軽量な ORM／LINQ プロバイダーである [linq2db](https://github.com/linq2db/linq2db) に対応しています。詳細なドキュメントについては、プロジェクトの Web サイトを参照してください。
**使用例:**
ClickHouse プロバイダーを使用して `DataConnection` を作成します。
```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);
```
テーブルのマッピングは、属性または Fluent API を使用して定義できます。クラス名とプロパティ名がテーブル名およびカラム名と完全に一致している場合は、設定は不要です。
```csharp theme={null}
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
}
```
**クエリの実行:**
```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();
```
**バルクコピー:**
効率的な一括挿入には `BulkCopyAsync` を使用します。
```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
ClickHouse 向けの公式 Entity Framework Core プロバイダーです。C# クラスを ClickHouse テーブルにマッピングし、LINQ でクエリを実行し、`SaveChanges` を通じてデータを insert できます。いずれも使い慣れた EF Core のパターンで行えます。
* **NuGet**: [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **Source**: [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
このプロバイダーは現在も活発に開発が進められています。現行の release では、LINQ クエリ (JOIN、subqueries、set operations を含む) 、`SaveChanges` / `BulkInsertAsync` による `INSERT`、完全な DDL (CREATE / ALTER / DROP) を伴う移行、そして ClickHouse 固有の table engine 設定をサポートしています。`UPDATE` / `DELETE` には対応していません。
#### インストール
```bash theme={null}
dotnet add package ClickHouse.EntityFrameworkCore
```
.NET 10.0 と EF Core 10 が必要です。
#### クイックスタート
エンティティと`DbContext`を定義し、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");
}
// クエリ
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();
```
#### サポートされる型
| カテゴリ | ClickHouse 型 | CLR 型 |
| ----------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **整数** | `Int8`–`Int64`, `UInt8`–`UInt64` | `sbyte`, `short`, `int`, `long`, `byte`, `ushort`, `uint`, `ulong` |
| **大きな整数** | `Int128`, `Int256`, `UInt128`, `UInt256` | `BigInteger` |
| **浮動小数点数** | `Float32`, `Float64`, `BFloat16` | `float`, `double` |
| **Decimal** | `Decimal(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` または `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **String** | `String`, `FixedString(N)` | `string` |
| **列挙型** | `Enum8(...)`, `Enum16(...)` | `string` または C# `enum` |
| **日付/時刻** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **Time** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **ネットワーク** | `IPv4`, `IPv6` | `IPAddress` |
| **Array** | `Array(T)` | `T[]`, `List`, `IList`, `ICollection`, `IReadOnlyList`, `IReadOnlyCollection`, `IEnumerable` |
| **Map** | `Map(K, V)` | `Dictionary` |
| **Tuple** | `Tuple(T1, ...)` | `Tuple<...>` または `ValueTuple<...>` |
| **Variant** | `Variant(T1, T2, ...)` | `object` |
| **Dynamic** | `Dynamic` | `object` |
| **JSON** | `Json` | `JsonNode` または `string` |
| **地理空間** | `Point`, `Ring`, `LineString`, `Polygon`, `MultiLineString`, `MultiPolygon`, `Geometry` | `Tuple` とその配列。`Geometry` には `object` |
| **ラッパー型** | `Nullable(T)`, `LowCardinality(T)` | 自動的にアンラップされます |
`Decimal128`/`Decimal256` カラムの完全な精度が必要な場合は、`decimal` ではなく `ClickHouseDecimal` (`ClickHouse.Driver.Numerics` のもの) を使用してください。.NET の `decimal` は有効桁数が 28～29 桁に制限されます。
#### サポートされている LINQ 操作
**クエリ:** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY と集計:** `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` を伴う `GroupBy` — `HAVING` (`.GroupBy()` の後に `.Where()` を使用) 、1 つのプロジェクション内での複数の集計、集計結果に対する `OrderBy` を含みます。
**JOIN:** `Join` (INNER) 、`GroupJoin`/`SelectMany` パターン (LEFT および CROSS) 。LEFT JOIN は、一致しない行に対して実際の `null` 値を返します (下記の [LEFT JOIN の NULL セマンティクス](#ef-core-join-nulls) を参照) 。
**サブクエリ:** 相関 `Contains` / `IN`、`Any` / `EXISTS`、`All`、およびプロジェクション内のスカラー サブクエリ。
**集合演算:** `Concat` (→ `UNION ALL`) 、`Union` (→ `UNION DISTINCT`) 、`Intersect`、`Except`。
**インラインのローカルコレクション:** インメモリコレクション (`int[]`、`List` など) に対する join や `Contains` は、一連の UNION に変換されます。
**文字列メソッド:** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (および `+` 演算子) 。
**数学関数:** 標準の `Math` および `MathF` メソッドは、対応する ClickHouse の関数に変換されます — 算術、対数、三角、およびユーティリティ関数。
##### LEFT JOIN の NULL セマンティクス
このプロバイダーは、JOIN の挙動に関する Entity Framework の想定に合わせるため、接続のたびに `set_join_use_nulls=1` を自動的に設定します。
ClickHouse サーバーまたは profile でこの設定の変更が禁止されている場合 (例: `readonly=1` の profile) 、次のように無効化してください。
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
オプトアウトが有効な場合、LEFT JOIN は ClickHouse のカラムのデフォルト値を返すため、EF の null ベースのナビゲーション検出は期待どおりに機能しなくなります。`== null` の代わりに、`0` / `""` との明示的な比較を使用してください。
#### データの挿入
`SaveChanges` では、ドライバーが提供するネイティブの `InsertBinaryAsync` API を使用します。RowBinary エンコーディングと GZip 圧縮を利用するため、パラメーター化 SQL よりもはるかに効率的です。
```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();
```
エンティティは、保存後に他の EF Core プロバイダーと同様、`Added` から `Unchanged` に変わります。
**バッチサイズ** は設定できます (デフォルトは 1000) :
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### 一括挿入
高スループットの読み込みでは、`SaveChanges` ではなく `BulkInsertAsync` を使用してください。これは `DbContext` の拡張メソッドで、EF Core の変更トラッカー、ID 解決、状態管理を完全にバイパスし、RowBinary エンコーディングと GZip 圧縮を使用して、ドライバーの `InsertBinaryAsync` を直接呼び出します。
そのため、挿入後にエンティティの追跡が不要な大規模データセットの読み込みに適しています。
```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);
```
入力には任意の `IEnumerable` を使用できます。エンティティはすべてをメモリに読み込むことなく順次処理されます。戻り値は挿入された行数です。挿入後もエンティティは `DbContext` にアタッチされないため、`Added` → `Unchanged` の状態遷移は発生しません。
#### 列挙型
ClickHouse `Enum8`/`Enum16` カラムは、`string` プロパティまたは C# の `enum` 型にマッピングできます。C# の列挙型を使用する場合、プロバイダーは列挙型とその文字列表現の間で自動的に変換します。
```csharp theme={null}
public enum Status { Active, Inactive, Pending }
public class User
{
public long Id { get; set; }
public Status Status { get; set; }
}
// enum値を使ったクエリ
var active = await ctx.Users
.Where(u => u.Status == Status.Active)
.ToListAsync();
```
#### カスタム型の変換
EF Core の `ValueConverter` システムを使うと、カスタム型をプロバイダーがすでにサポートしている型にマッピングできます。プロバイダーがカスタム型を直接扱うことはなく、EF Core がその境界で変換を行います。
**プロパティ単位の変換:**
```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; }
}
// 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");
```
**再利用可能なコンバータークラス:**
```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] };
}
}
// 単一のプロパティに適用する場合:
.HasConversion()
// または、規約を使用して型のすべてのプロパティに適用する場合:
protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
configurationBuilder.Properties()
.HaveConversion();
}
```
#### カラム型のアノテーション
`string`、`int`、`DateTime` などのスカラー型では、プロバイダーが ClickHouse の型を自動的に推論します。パラメーター化された型やラッパーについては、ClickHouse の型を明示的に指定する必要があります。
**データ アノテーション (属性) を使用する場合:**
```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; }
}
```
**`OnModelCreating` で fluent API を使用する方法:**
```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)");
});
```
`Array(Nullable(Int32))` や `LowCardinality(Nullable(String))` のようなネストされたラッパー型をサポートしています — プロバイダーは `Nullable` と `LowCardinality` をどのネストレベルでも自動的にアンラップします。
#### Variant と Dynamic カラム
ClickHouse の `Variant(T1, T2, ...)` カラムおよび `Dynamic` カラムは、.NET では `object` にマップされます。`object` は自動的な型推論には汎用的すぎるため、`.HasColumnType()` でストア型を明示的に指定する必要があります。
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public object? Payload { get; set; }
}
// OnModelCreating 内:
entity.Property(e => e.Payload).HasColumnType("Variant(String, UInt64, Array(UInt64))");
// または:
entity.Property(e => e.Payload).HasColumnType("Dynamic");
```
読み取り時には、値は保存されている判別子に対応する .NET 型 (例: `string`、`ulong`、`ulong[]`) に自動的にデシリアライズされます。
#### JSON カラム
このプロバイダーは ClickHouse の `Json` カラム型をサポートしており、`System.Text.Json.Nodes.JsonNode` (プライマリ) または `string` (自動 `ValueConverter` 使用時) に対応付けられます。
```csharp theme={null}
using System.Text.Json.Nodes;
public class Event
{
public long Id { get; set; }
public JsonNode? Data { get; set; }
}
// OnModelCreating 内:
entity.Property(e => e.Data).HasColumnType("Json");
```
JSON の読み書きは、`SaveChanges` と `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"
```
生の JSON 文字列を使いたい場合は、プロパティを `string` として `Json` カラム型にマップしてください。プロバイダーが `ValueConverter` を自動的に適用します。
```csharp theme={null}
public class Event
{
public long Id { get; set; }
public string? Data { get; set; } // 生のJSON文字列
}
entity.Property(e => e.Data).HasColumnType("Json");
```
* **JSON パスは変換されません** — LINQ の `entity.Data["name"]` は、ClickHouse の `data.name` という SQL 構文には変換されません。JSON 以外のカラムでフィルタし、JSON はメモリ上で確認してください。
* **NULL セマンティクス** — ClickHouse の JSON type は、NULL 値に対して SQL NULL ではなく `{}` (空のオブジェクト) を返します。
* **整数の精度** — ClickHouse の JSON は、すべての整数を `Int64` として格納します。`JsonNode` 経由で読み取る場合は、`GetValue()` ではなく `GetValue()` を使用してください。
#### テーブルエンジン
`ToTable(name, t => ...)` のフルーエント API を使用して、ClickHouse テーブルのエンジンとエンジン固有の句を設定します。エンジンが設定されていない場合、プロバイダーは既定で `MergeTree` を使用し、`ORDER BY` はエンティティの主キーに基づいて決定されます。
```csharp theme={null}
modelBuilder.Entity(e =>
{
e.ToTable("events", t => t
.HasMergeTreeEngine()
.WithOrderBy("UserId", "Timestamp")
.WithPartitionBy("toYYYYMM(Timestamp)")
.WithPrimaryKey("UserId")
.WithSettings("index_granularity = 8192"));
});
```
サポートされているエンジンファミリー:
| Engine | Fluent method | Notes |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `MergeTree` | `HasMergeTreeEngine()` | 設定がない場合のデフォルト |
| `ReplacingMergeTree` | `HasReplacingMergeTreeEngine("Version", "IsDeleted")` or `HasReplacingMergeTreeEngine(e => e.Version)` | `Version` / `IsDeleted` カラムは省略可能 |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` or `HasSummingMergeTreeEngine(e => new { … })` | 合計対象のカラムは省略可能 |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` or `HasCollapsingMergeTreeEngine(e => e.Sign)` | `Sign` カラムは `Int8` である必要があります |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` or `(e => e.Sign, e => e.Version)` | — |
| `GraphiteMergeTree` | `HasGraphiteMergeTreeEngine("config_section")` | — |
| `Log`, `TinyLog`, `StripeLog`, `Memory` | `HasLogEngine()`, `HasTinyLogEngine()`, `HasStripeLogEngine()`, `HasMemoryEngine()` | ORDER BY / PARTITION BY は使用不可 |
**エンジン句:** `WithOrderBy`, `WithPartitionBy`, `WithPrimaryKey`, `WithSampleBy`, `WithTtl`, `WithSettings`。いずれも `HasXxxEngine()` が返すエンジンビルダーに対して指定します。
**カラムレベルの機能:** `HasCodec`, `HasTtl`, `HasComment`, `HasDefault` — いずれも移行の対象になります。
**データスキッピング索引** — `HasIndex(...).HasSkippingIndexType(...)` で指定します:
```csharp theme={null}
modelBuilder.Entity()
.HasIndex(e => e.UserId)
.HasSkippingIndexType("minmax")
.HasGranularity(4);
// パラメータ付きインデックス（例: bloom_filter、tokenbf_v1）:
modelBuilder.Entity()
.HasIndex(e => e.Tag)
.HasSkippingIndexType("bloom_filter")
.HasSkippingIndexParams("0.01")
.HasGranularity(1);
```
標準の (スキップしない) 索引は、ClickHouse に相当するものがないため、黙って無視されます。一意索引については、ClickHouse では一意性が保証されないため、例外がスローされます。
#### 移行
標準的な EF Core の移行ワークフロー:
```bash theme={null}
dotnet ef migrations add InitialCreate
dotnet ef database update
```
サポートされている操作:
| 操作 | 生成内容 |
| -------------------------------------- | --------------------------------------------------------------------- |
| `CREATE TABLE` | engine 句、ORDER BY、PARTITION BY、SETTINGS、カラムの codec/TTL/コメント/デフォルト値を含む |
| `ALTER TABLE ADD COLUMN` | — |
| `ALTER TABLE DROP COLUMN` | — |
| `ALTER TABLE MODIFY COLUMN` | 型変更に加え、属性の追加/削除 (CODEC、TTL、COMMENT、DEFAULT) に対応 |
| `ALTER TABLE RENAME COLUMN` | — |
| `RENAME TABLE` | — |
| `ALTER TABLE ADD INDEX` / `DROP INDEX` | データスキッピング索引のみ |
| `CREATE DATABASE` / `DROP DATABASE` | `EnsureCreated` / `EnsureDeleted` および移行を介して実行 |
#### 移行の制限事項
| 機能 | 理由 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 外部キー | ClickHouse は外部キーを強制しません。移行では `AddForeignKey` は拒否され、モデル バリデーターはモデルのビルド時に警告を出します。 |
| 一意制約 / 一意索引 | ClickHouse は一意性を保証しません。一意索引は移行時に例外をスローします。 |
| サーバー生成値 (auto-increment / `IDENTITY`) | ClickHouse に相当する機能はありません。 |
| `Nested(…)` カラム | マップされた CLR 型としてはまだサポートされていません。 |
| JSON としての所有エンティティ (`.ToJson()`) | 所有エンティティに対する構造的な JSON マッピングはまだ実装されていません。代わりに、`Json` カラムで `JsonNode` / `string` を使用してください ([JSON カラム](#ef-core-json) を参照) 。 |
移行以外にも、このプロバイダーはまだ以下をサポートしていません。
* **`UPDATE` / `DELETE`**
* **トランザクション**: `BeginTransaction` は no-op です。ClickHouse は ACID トランザクションをサポートしていません。
* **JSON パス クエリの変換**: LINQ の `entity.Data["key"]` は、ClickHouse の `data.key` SQL 構文に変換されません。JSON 以外のカラムでフィルタリングし、JSON はメモリ上で確認してください。
## 制限事項
### AggregateFunction カラム
`AggregateFunction(...)` 型のカラムは、直接クエリしたり、挿入したりすることはできません。
挿入するには:
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
取得するには:
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***