ClickHouse C# client

- **`Binary` (default)**: Returns `System.Text.Json.Nodes.JsonObject`. Provides structured access to JSON data, but specialized ClickHouse types (like IP addresses, UUIDs, large decimals) are converted to their string representations within the JSON structure.
- **`String`**: Returns the raw JSON as a `string`. Preserves the exact JSON representation from ClickHouse, which is useful when you need to pass the JSON through without parsing, or when you want to handle deserialization yourself.

```
// Configure string mode via settings
var settings = new ClickHouseClientSettings("Host=localhost")
{
    JsonReadMode = JsonReadMode.String
};

// Or via connection string
// "Host=localhost;JsonReadMode=String"
```

---

#### Other types[​](#type-map-reading-other "Direct link to Other types")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type .NET Type|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UUID `Guid`| IPv4 `IPAddress`| IPv6 `IPAddress`| Nothing `DBNull`| Dynamic See note|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Array(T) `T[]`| Tuple(T1, T2, ...) `Tuple<T1, T2, ...>` / `LargeTuple`| Map(K, V) `Dictionary<K, V>`| Nullable(T) `T?`| Enum8 `string`| Enum16 `string`| LowCardinality(T) Same as T|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | SimpleAggregateFunction Same as underlying type|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Nested(...) `Tuple[]`| Variant(T1, T2, ...) See note|  |  | | --- | --- | | QBit(T, dimension) `T[]` | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Note

The Dynamic and Variant types will be converted to the corresponding type for the actual underlying type in each row.

---

#### Geometry types[​](#type-map-reading-geometry "Direct link to Geometry types")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type .NET Type|  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Point `Tuple<double, double>`| Ring `Tuple<double, double>[]`| LineString `Tuple<double, double>[]`| Polygon `Ring[]`| MultiLineString `LineString[]`| MultiPolygon `Polygon[]`| Geometry See note | | | | | | | | | | | | | | | |

Note

The Geometry type is a Variant type that can hold any of the geometry types. It will be converted to the corresponding type.

---

### Type mapping: writing to ClickHouse[​](#clickhouse-native-type-map-writing "Direct link to Type mapping: writing to ClickHouse")

When inserting data, the driver converts .NET types to their corresponding ClickHouse types. The tables below show which .NET types are accepted for each ClickHouse column type.

#### Integer types[​](#type-map-writing-integer "Direct link to Integer types")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Int8 `sbyte`, any `Convert.ToSByte()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UInt8 `byte`, any `Convert.ToByte()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Int16 `short`, any `Convert.ToInt16()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UInt16 `ushort`, any `Convert.ToUInt16()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Int32 `int`, any `Convert.ToInt32()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UInt32 `uint`, any `Convert.ToUInt32()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Int64 `long`, any `Convert.ToInt64()` compatible |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UInt64 `ulong`, any `Convert.ToUInt64()` compatible |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Int128 `BigInteger`, `decimal`, `double`, `float`, `int`, `uint`, `long`, `ulong`, any `Convert.ToInt64()` compatible |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UInt128 `BigInteger`, `decimal`, `double`, `float`, `int`, `uint`, `long`, `ulong`, any `Convert.ToInt64()` compatible |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Int256 `BigInteger`, `decimal`, `double`, `float`, `int`, `uint`, `long`, `ulong`, any `Convert.ToInt64()` compatible |  |  |  | | --- | --- | --- | | UInt256 `BigInteger`, `decimal`, `double`, `float`, `int`, `uint`, `long`, `ulong`, any `Convert.ToInt64()` compatible  | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

---

#### Floating point types[​](#type-map-writing-floating-point "Direct link to Floating point types")

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ClickHouse Type Accepted .NET Types Notes|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Float32 `float`, any `Convert.ToSingle()` compatible |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Float64 `double`, any `Convert.ToDouble()` compatible |  |  |  | | --- | --- | --- | | BFloat16 `float`, any `Convert.ToSingle()` compatible Truncates to 16-bit brain float format | | | | | | | | | | | |

---

#### 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")