ClickHouse C# client

---

#### Boolean type[​](#type-map-writing-boolean "Direct link to Boolean type")

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  | | --- | --- | --- | | Bool `bool`  | | | | | |

---

#### String types[​](#type-map-writing-strings "Direct link to String types")

|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | String `string`, `byte[]`, `ReadOnlyMemory<byte>`, `Stream` Binary types written directly; streams can be seekable or non-seekable|  |  |  | | --- | --- | --- | | FixedString(N) `string`, `byte[]`, `ReadOnlyMemory<byte>`, `Stream` String is UTF-8 encoded and padded; binary types must be exactly N bytes | | | | | | | | |

---

#### Date and time types[​](#type-map-writing-datetime "Direct link to Date and time types")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Date `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime types Converted to Unix days as UInt16|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Date32 `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime types Converted to Unix days as Int32|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | DateTime `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime types See below for details|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | DateTime32 `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime types Same as DateTime|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | DateTime64 `DateTime`, `DateTimeOffset`, `DateOnly`, NodaTime types Precision based on Scale parameter|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Time `TimeSpan`, `int` Clamped to ±999:59:59; int treated as seconds|  |  |  | | --- | --- | --- | | Time64 `TimeSpan`, `decimal`, `double`, `float`, `int`, `long`, `string` String parsed as `[-]HHH:MM:SS[.fraction]`; clamped to ±999:59:59.999999999 | | | | | | | | | | | | | | | | | | | | | | | |

The driver respects `DateTime.Kind` when writing values:

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DateTime.Kind HTTP Parameters Bulk|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Utc Instant preserved Instant preserved|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Local Instant preserved Instant preserved|  |  |  | | --- | --- | --- | | Unspecified Treated as wall-clock in parameter type's timezone (defaults to UTC) Treated as wall-clock in column's timezone | | | | | | | | | | | |

`DateTimeOffset` values always preserve the exact instant.

**Example: UTC DateTime (instant preserved)**

```
var utcTime = new DateTime(2024, 1, 15, 12, 0, 0, DateTimeKind.Utc);
// Stored as 12:00 UTC
// Read from DateTime('Europe/Amsterdam') column: 13:00 (UTC+1)
// Read from DateTime('UTC') column: 12:00 UTC
```

**Example: unspecified DateTime (wall-clock time)**

```
var wallClock = new DateTime(2024, 1, 15, 14, 30, 0, DateTimeKind.Unspecified);
// Written to DateTime('Europe/Amsterdam') column: stored as 14:30 Amsterdam time
// Read back from DateTime('Europe/Amsterdam') column: 14:30
```

**Recommendation:** for simplest and most predictable behavior, use `DateTimeKind.Utc` or `DateTimeOffset` for all DateTime operations. This ensures your code works consistently regardless of server timezone, client timezone, or column timezone.

#### HTTP parameters vs bulk copy[​](#datetime-http-param-vs-bulkcopy "Direct link to HTTP parameters vs bulk copy")

There is an important difference between HTTP parameter binding and bulk copy when writing `Unspecified` DateTime values:

**Bulk Copy** knows the target column's timezone and correctly interprets `Unspecified` values in that timezone.

**HTTP Parameters** do not automatically know the column timezone. You must specify it in the SQL type hint:

```
// CORRECT: Timezone in SQL type hint - type is extracted automatically
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime('Europe/Amsterdam')})";
command.AddParameter("dt", myDateTime);

// INCORRECT: Without timezone hint, interpreted as UTC
command.CommandText = "INSERT INTO table (dt_amsterdam) VALUES ({dt:DateTime})";
command.AddParameter("dt", myDateTime);
// String value "2024-01-15 14:30:00" interpreted as UTC, not Amsterdam time!
```

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `DateTime.Kind` Target Column HTTP Param (with tz hint) HTTP Param (no tz hint) Bulk Copy|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Utc` UTC Instant preserved Instant preserved Instant preserved|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Utc` Europe/Amsterdam Instant preserved Instant preserved Instant preserved|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Local` Any Instant preserved Instant preserved Instant preserved|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Unspecified` UTC Treated as UTC Treated as UTC Treated as UTC|  |  |  |  |  | | --- | --- | --- | --- | --- | | `Unspecified` Europe/Amsterdam Treated as Amsterdam time **Treated as UTC** Treated as Amsterdam time | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

---

#### Decimal types[​](#type-map-writing-decimal "Direct link to Decimal types")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Decimal(P,S) `decimal`, `ClickHouseDecimal`, any `Convert.ToDecimal()` compatible Throws `OverflowException` if exceeds precision| Decimal32 `decimal`, `ClickHouseDecimal`, any `Convert.ToDecimal()` compatible Max precision 9|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Decimal64 `decimal`, `ClickHouseDecimal`, any `Convert.ToDecimal()` compatible Max precision 18|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Decimal128 `decimal`, `ClickHouseDecimal`, any `Convert.ToDecimal()` compatible Max precision 38|  |  |  | | --- | --- | --- | | Decimal256 `decimal`, `ClickHouseDecimal`, any `Convert.ToDecimal()` compatible Max precision 76 | | | | | | | | | | | | | | | | | |

---

#### JSON type[​](#type-map-writing-json "Direct link to JSON type")

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  | | --- | --- | --- | | Json `string`, `JsonObject`, `JsonNode`, any object Behavior depends on `JsonWriteMode` setting | | | | | |