> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Официальный клиент C# для подключения к ClickHouse.
# Клиент ClickHouse для C#
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
Официальный клиент C# для подключения к ClickHouse.
Исходный код клиента доступен в [репозитории GitHub](https://github.com/ClickHouse/clickhouse-cs).
Изначально разработан [Oleg V. Kozlyuk](https://github.com/DarkWanderer).
Библиотека предоставляет два основных API:
* **`ClickHouseClient`** (рекомендуется): высокоуровневый потокобезопасный клиент, предназначенный для использования в качестве singleton. Предоставляет простой асинхронный API для запросов и массовых вставок. Лучше всего подходит для большинства приложений.
* **ADO.NET** (`ClickHouseDataSource`, `ClickHouseConnection`, `ClickHouseCommand`): стандартные абстракции базы данных в .NET. Требуются для интеграции с ORM (Dapper, Linq2db) и в случаях, когда нужна совместимость с ADO.NET. `ClickHouseBulkCopy` — вспомогательный класс для эффективной вставки данных с использованием ADO.NET-соединения. `ClickHouseBulkCopy` устарел и будет удалён в одном из будущих релизов; вместо него используйте `ClickHouseClient.InsertBinaryAsync`.
Оба API используют один и тот же базовый пул HTTP-соединений и могут применяться вместе в одном приложении.
## Руководство по миграции
1. Обновите файл `.csproj`: укажите новое имя пакета `ClickHouse.Driver` и [последнюю версию на NuGet](https://www.nuget.org/packages/ClickHouse.Driver).
2. Замените в кодовой базе все упоминания `ClickHouse.Client` на `ClickHouse.Driver`.
***
## Поддерживаемые версии .NET
`ClickHouse.Driver` поддерживает следующие версии .NET:
* .NET 6.0
* .NET 8.0
* .NET 9.0
* .NET 10.0
## Поддерживаемые версии ClickHouse
Клиент официально поддерживает три последних релиза, а также два последних LTS-релиза.
## Установка
Установите пакет из NuGet:
```bash theme={null}
dotnet add package ClickHouse.Driver
```
Или через диспетчер пакетов NuGet:
```bash theme={null}
Install-Package ClickHouse.Driver
```
## Быстрый старт
```csharp theme={null}
using ClickHouse.Driver;
// Создание клиента (обычно как singleton)
using var client = new ClickHouseClient("Host=my.clickhouse;Protocol=https;Port=8443;Username=user");
// Выполнение запроса
var version = await client.ExecuteScalarAsync("SELECT version()");
Console.WriteLine(version);
```
## Конфигурация
Существует два способа настроить подключение к ClickHouse:
* **Строка подключения:** пары ключ/значение, разделённые точкой с запятой, которые задают хост, учётные данные для аутентификации и другие параметры подключения.
* **Объект `ClickHouseClientSettings`:** строго типизированный объект конфигурации, который можно загрузить из файлов конфигурации или задать в коде.
Ниже приведён полный список всех настроек, их значений по умолчанию и того, как они влияют на работу.
### Настройки подключения
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| -------- | ---------- | -------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| Host | `string` | `"localhost"` | `Host` | Имя хоста или IP-адрес сервера ClickHouse |
| Port | `ushort` | 8123 (HTTP) / 8443 (HTTPS) | `Port` | Номер порта; значение по умолчанию зависит от протокола |
| Username | `string` | `"default"` | `Username` | Имя пользователя для аутентификации |
| Password | `string` | `""` | `Password` | Пароль для аутентификации |
| Database | `string` | `""` | `Database` | База данных по умолчанию; если значение пустое, используются настройки сервера или пользователя по умолчанию |
| Protocol | `string` | `"http"` | `Protocol` | Протокол подключения: `"http"` или `"https"` |
| Path | `string` | `null` | `Path` | URL-путь для сценариев с использованием обратного прокси (например, `/clickhouse`) |
| Timeout | `TimeSpan` | 2 минуты | `Timeout` | Тайм-аут операции (в строке подключения хранится в секундах) |
### Формат данных и сериализация
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| ----------------------- | ------------------------ | -------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UseCompression | `bool` | `true` | `Compression` | Включает gzip-сжатие при передаче данных |
| UseCustomDecimals | `bool` | `true` | `UseCustomDecimals` | Использовать `ClickHouseDecimal` для чисел произвольной точности; если `false`, используется .NET `decimal` (предел — 128 бит) |
| ReadStringsAsByteArrays | `bool` | `false` | `ReadStringsAsByteArrays` | Читать столбцы `String` и `FixedString` как `byte[]` вместо `string`; полезно для бинарных данных |
| UseFormDataParameters | `bool` | `false` | `UseFormDataParameters` | Отправлять параметры в виде form data, а не в строке запроса URL |
| ReadBufferSize | `int` | `8192` (8 KiB) | `ReadBufferSize` | Размер буфера в байтах, используемого для чтения HTTP-ответов на запросы. Увеличьте его, чтобы сократить число повторных заполнений буфера для больших результирующих наборов. Значения от 85 000 байт и выше выделяются в Large Object Heap, что может вызывать фрагментацию LOH и более длительные паузы GC. |
| ParameterTypeResolver | `IParameterTypeResolver` | `null` | — | Пользовательский резолвер для сопоставления типов параметров в стиле `@`; см. [Пользовательское сопоставление типов параметров](#parameter-type-mapping) |
| ParameterFormatter | `IParameterFormatter` | `null` | — | Пользовательский форматтер для сериализации значений параметров; см. [Пользовательское форматирование значений параметров](#parameter-value-formatting) |
| ReadValueConverter | `IReadValueConverter` | `null` | — | Пользовательское преобразование, применяемое к значениям, возвращаемым средством чтения данных; см. [Пользовательское преобразование значений при чтении](#read-value-conversion) |
| JsonReadMode | `JsonReadMode` | `Binary` | `JsonReadMode` | Как возвращаются данные JSON: `Binary` (возвращает `JsonObject`) или `String` (возвращает сырую JSON-строку) |
| JsonWriteMode | `JsonWriteMode` | `String` | `JsonWriteMode` | Как отправляются данные JSON: `String` (сериализует через `JsonSerializer`, принимает любые входные данные) или `Binary` (только зарегистрированные POCO с подсказками типов) |
### Управление сеансами
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| ---------- | -------- | ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------- |
| UseSession | `bool` | `false` | `UseSession` | Включает сеансы с сохранением состояния; запросы выполняются последовательно |
| SessionId | `string` | `null` | `SessionId` | Идентификатор сеанса; GUID генерируется автоматически, если `null` и `UseSession` имеет значение `true` |
Флаг `UseSession` включает сохранение сеанса на сервере, что позволяет использовать операторы `SET` и временные таблицы. Сеансы сбрасываются после 60 секунд бездействия (тайм-аут по умолчанию). Время жизни сеанса можно увеличить, задав настройку сеанса через команды ClickHouse или конфигурацию сервера.
Класс `ClickHouseConnection` обычно поддерживает параллельную работу (несколько потоков могут выполнять запросы одновременно). Однако при включении флага `UseSession` для одного подключения в любой момент времени будет доступен только один активный запрос (это ограничение на стороне сервера).
### Безопасность
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| ------------------------------- | ------ | ------------ | ----------------------- | ---------------------------------------------------------------------- |
| SkipServerCertificateValidation | `bool` | `false` | — | Пропустить проверку HTTPS-сертификата; **не использовать в продакшне** |
### Конфигурация HTTP-клиента
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| ----------------- | -------------------- | ------------ | ----------------------- | -------------------------------------------------------------------------- |
| HttpClient | `HttpClient` | `null` | — | Пользовательский предварительно настроенный экземпляр HttpClient |
| HttpClientFactory | `IHttpClientFactory` | `null` | — | Пользовательская фабрика для создания экземпляров HttpClient |
| HttpClientName | `string` | `null` | — | Имя, которое HttpClientFactory использует для создания конкретного клиента |
### Логирование и отладка
| Свойство | Тип | По умолчанию | Ключ строки подключения | Описание |
| --------------- | ---------------- | ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| LoggerFactory | `ILoggerFactory` | `null` | — | Фабрика логгеров для диагностического логирования |
| EnableDebugMode | `bool` | `false` | — | Включает сетевую трассировку .NET (требуется LoggerFactory с уровнем Trace); **существенно влияет на производительность** |
### Пользовательские настройки и роли
| Property | Type | Default | Connection String Key | Description |
| --------------- | ------------------------------------- | ------- | --------------------- | ----------------------------------------------------------------------------------------------- |
| CustomSettings | `IDictionary` | Пусто | префикс `set_*` | настройки сервера ClickHouse, см. примечание ниже |
| Roles | `IReadOnlyList` | Пусто | `Roles` | Роли ClickHouse, разделённые запятыми (например, `Roles=admin,reader`) |
| ApplicationInfo | `IReadOnlyDictionary` | Пусто | — | Произвольные теги, добавляемые в HTTP-заголовок `User-Agent` для атрибуции запросов приложению. |
Если вы задаёте пользовательские настройки через строку подключения, используйте префикс `set_`, например: "set\_max\_threads=4". Если вы используете объект ClickHouseClientSettings, префикс `set_` указывать не нужно.
Полный список доступных настроек см. [здесь](/docs/ru/reference/settings/session-settings).
***
### Примеры строк подключения
#### Базовое подключение
```text theme={null}
Host=localhost;Port=8123;Username=default;Password=secret;Database=mydb
```
#### С пользовательскими настройками ClickHouse
```text theme={null}
Host=localhost;set_max_threads=4;set_readonly=1;set_max_memory_usage=10000000000
```
***
### QueryOptions
`QueryOptions` позволяет переопределять настройки уровня клиента для отдельных запросов. Все свойства необязательны и переопределяют значения клиента по умолчанию только если они указаны.
| Свойство | Тип | Описание |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| QueryId | `string` | Пользовательский идентификатор запроса для отслеживания в `system.query_log` или отмены |
| Database | `string` | Переопределяет базу данных по умолчанию для этого запроса |
| Roles | `IReadOnlyList` | Переопределяет роли клиента для этого запроса |
| CustomSettings | `IDictionary` | Настройки сервера ClickHouse для этого запроса (например, `max_threads`) |
| CustomHeaders | `IDictionary` | Дополнительные HTTP-заголовки для этого запроса |
| UseSession | `bool?` | Переопределяет поведение сеанса для этого запроса |
| SessionId | `string` | Идентификатор сеанса для этого запроса (требуется `UseSession = true`) |
| BearerToken | `string` | Переопределяет токен аутентификации для этого запроса |
| ParameterTypeResolver | `IParameterTypeResolver` | Переопределяет резолвер уровня клиента для сопоставления типов параметров в стиле `@`; см. [Пользовательское сопоставление типов параметров](#parameter-type-mapping) |
| ParameterFormatter | `IParameterFormatter` | Переопределяет форматтер уровня клиента для сериализации значений параметров в стиле `@`; см. [Пользовательское форматирование значений параметров](#parameter-value-formatting) |
| ReadValueConverter | `IReadValueConverter` | Переопределяет преобразование уровня клиента, применяемое к значениям, возвращаемым средством чтения данных; см. [Пользовательское преобразование значений при чтении](#read-value-conversion) |
| MaxExecutionTime | `TimeSpan?` | Тайм-аут запроса на стороне сервера (передаётся как настройка `max_execution_time`); сервер отменяет запрос при превышении |
| AcceptEncoding | `string` | Переопределяет заголовок `Accept-Encoding` для отдельного запроса (например, `"zstd"`, `"zstd, gzip;q=0.5"`); также принудительно задаёт `enable_http_compression=1` в URL. См. [Сжатие передачи для отдельного запроса](#per-query-accept-encoding). |
**Пример:**
```csharp theme={null}
var options = new QueryOptions
{
QueryId = "report-2024-001",
Database = "analytics",
CustomSettings = new Dictionary
{
{ "max_threads", 4 },
{ "max_memory_usage", 10_000_000_000 }
},
MaxExecutionTime = TimeSpan.FromMinutes(5)
};
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM large_table",
parameters: null,
options: options
);
```
***
### InsertOptions
`InsertOptions` дополняет `QueryOptions` настройками, специфичными для пакетных операций вставки через `InsertBinaryAsync`.
| Свойство | Тип | По умолчанию | Описание |
| ---------------------- | ------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
| BatchSize | `int` | 100,000 | Количество строк в батче |
| MaxDegreeOfParallelism | `int` | 1 | Количество параллельных загрузок батчей |
| Format | `RowBinaryFormat` | `RowBinary` | Бинарный формат: `RowBinary` или `RowBinaryWithDefaults` |
| ColumnTypes | `IReadOnlyDictionary` | `null` | Имя столбца → строка типа ClickHouse. Если задано, запрос для определения схемы пропускается. |
| UseSchemaCache | `bool` | `false` | Кэшировать полную схему таблицы для каждой пары (database, table) на всё время жизни клиента. |
Все свойства `QueryOptions` также доступны в `InsertOptions`.
**Пример:**
```csharp theme={null}
var insertOptions = new InsertOptions
{
BatchSize = 50_000,
MaxDegreeOfParallelism = 4,
QueryId = "bulk-import-001"
};
long rowsInserted = await client.InsertBinaryAsync(
"my_table",
columns,
rows,
insertOptions
);
```
#### Пропуск запроса для определения схемы
По умолчанию `InsertBinaryAsync` перед каждой вставкой отправляет запрос `SELECT ... WHERE 1=0`, чтобы определить типы столбцов. В сценариях с высокой пропускной способностью эти накладные расходы можно исключить двумя способами:
**Вариант 1: Явно указать типы столбцов**
Если схема таблицы известна на этапе компиляции, передайте её напрямую через `ColumnTypes`. В этом случае запрос схемы вообще не отправляется:
```csharp theme={null}
var options = new InsertOptions
{
ColumnTypes = new Dictionary
{
["id"] = "UInt64",
["name"] = "Nullable(String)",
["score"] = "Float32",
},
};
await client.InsertBinaryAsync("my_table", ["id", "name", "score"], rows, options);
```
**Вариант 2: Кэшируйте схему**
Если вы многократно выполняете вставку в одну и ту же таблицу, установите `UseSchemaCache = true`, чтобы запросить схему один раз и повторно использовать её для последующих вставок через тот же экземпляр `ClickHouseClient`:
```csharp theme={null}
var options = new InsertOptions { UseSchemaCache = true };
// Первый вызов получает схему с сервера
await client.InsertBinaryAsync("my_table", columns, batch1, options);
// Второй вызов использует кэшированную схему — без лишних обращений к серверу
await client.InsertBinaryAsync("my_table", columns, batch2, options);
```
* `ColumnTypes` имеет приоритет над `UseSchemaCache`. Если заданы оба параметра, используются явно указанные типы.
* Кэш схемы не отслеживает изменения, внесённые командой `ALTER TABLE`. Если вы изменяете схему таблицы, создайте новый `ClickHouseClient` или не используйте `UseSchemaCache` для этой таблицы.
* Кэш привязан к экземпляру `ClickHouseClient`, а в качестве ключа используются (database, table). Разные подмножества столбцов одной и той же таблицы используют одну общую кэшированную схему.
## ClickHouseClient
`ClickHouseClient` — рекомендуемый API для работы с ClickHouse. Он потокобезопасен, рассчитан на использование как singleton и самостоятельно управляет пулом HTTP-соединений.
### Создание клиента
Создайте `ClickHouseClient` с помощью строки подключения или объекта `ClickHouseClientSettings`. Доступные параметры см. в разделе [Конфигурация](#configuration).
Сведения о вашем сервисе ClickHouse Cloud доступны в консоли ClickHouse Cloud.
Выберите сервис и нажмите **Connect**:
Выберите **C#**. Ниже отобразятся сведения о подключении.
Если вы используете самоуправляемый ClickHouse, сведения о подключении задаёт ваш администратор ClickHouse.
Использование строки подключения:
```csharp theme={null}
using ClickHouse.Driver;
using var client = new ClickHouseClient("Host=localhost;Username=default;Password=secret");
```
Или с помощью `ClickHouseClientSettings`:
```csharp theme={null}
using ClickHouse.Driver;
var settings = new ClickHouseClientSettings
{
Host = "localhost",
Username = "default",
Password = "secret"
};
using var client = new ClickHouseClient(settings);
```
Для сценариев с инъекцией зависимостей используйте `IHttpClientFactory`:
```csharp theme={null}
// In your DI configuration
services.AddHttpClient("ClickHouse", client =>
{
client.Timeout = TimeSpan.FromMinutes(5);
}).ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate
});
// Create client with factory
var factory = serviceProvider.GetRequiredService();
var client = new ClickHouseClient("Host=localhost", factory, "ClickHouse");
```
`ClickHouseClient` рассчитан на длительное использование и совместное использование во всём приложении. Создайте его один раз (обычно как singleton) и затем повторно используйте для всех операций с базой данных. Клиент сам управляет пулом HTTP-соединений.
***
### Выполнение запросов
Используйте `ExecuteNonQueryAsync` для команд, которые не возвращают результатов:
```csharp theme={null}
// Создать таблицу
await client.ExecuteNonQueryAsync(
"CREATE TABLE IF NOT EXISTS default.my_table (id Int64, name String) ENGINE = Memory"
);
// Удалить таблицу
await client.ExecuteNonQueryAsync("DROP TABLE IF EXISTS default.my_table");
```
Используйте `ExecuteScalarAsync`, чтобы получить единственное значение:
```csharp theme={null}
var count = await client.ExecuteScalarAsync("SELECT count() FROM default.my_table");
Console.WriteLine($"Количество строк: {count}");
var version = await client.ExecuteScalarAsync("SELECT version()");
Console.WriteLine($"Версия сервера: {version}");
```
***
### Вставка данных
#### Параметризованные вставки
Для вставки данных с помощью параметризованных запросов используйте `ExecuteNonQueryAsync`. Типы параметров должны быть указаны в SQL с использованием синтаксиса `{name:Type}`:
```csharp theme={null}
using ClickHouse.Driver;
using ClickHouse.Driver.ADO.Parameters;
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("id", 1L);
parameters.AddParameter("name", "Alice");
await client.ExecuteNonQueryAsync(
"INSERT INTO default.my_table (id, name) VALUES ({id:Int64}, {name:String})",
parameters
);
```
***
#### Массовая вставка
Используйте `InsertBinaryAsync` для эффективной вставки большого количества строк. Метод передает данные в потоковом режиме в нативном бинарном формате строк ClickHouse, поддерживает параллельную загрузку батчей и позволяет избежать ошибок "URL too long", которые могут возникать при параметризованных запросах.
```csharp theme={null}
// Подготовка данных как IEnumerable
var rows = Enumerable.Range(0, 1_000_000)
.Select(i => new object[] { (long)i, $"value{i}" });
var columns = new[] { "id", "name" };
// Базовая вставка
long rowsInserted = await client.InsertBinaryAsync("default.my_table", columns, rows);
Console.WriteLine($"Rows inserted: {rowsInserted}");
```
Для больших объёмов данных настройте пакетную обработку и степень параллелизма с помощью `InsertOptions`:
```csharp theme={null}
var options = new InsertOptions
{
BatchSize = 100_000, // Строк в батче (по умолчанию: 100 000)
MaxDegreeOfParallelism = 4 // Параллельная загрузка батчей (по умолчанию: 1)
};
```
* Перед вставкой клиент автоматически получает структуру таблицы с помощью `SELECT * FROM WHERE 1=0`. Передаваемые значения должны соответствовать типам целевых столбцов. Чтобы пропустить этот запрос, используйте [`InsertOptions.ColumnTypes` или `InsertOptions.UseSchemaCache`](#skip-schema-query).
* Если `MaxDegreeOfParallelism > 1`, батчи загружаются параллельно. Сеансы несовместимы с параллельной вставкой; либо отключите сеансы, либо задайте `MaxDegreeOfParallelism = 1`.
* Используйте `RowBinaryFormat.RowBinaryWithDefaults` в `InsertOptions.Format`, если хотите, чтобы сервер применял значения DEFAULT для столбцов, которые не были переданы.
#### Вставка POCO
Вместо создания массивов `object[]` можно напрямую вставлять строго типизированные объекты POCO. Зарегистрируйте тип один раз, а затем передайте `IEnumerable`:
```csharp theme={null}
// Определите POCO, соответствующий столбцам вашей таблицы
public class SensorReading
{
public ulong Id { get; set; }
public string SensorName { get; set; }
public double Value { get; set; }
public DateTime Timestamp { get; set; }
}
// Зарегистрируйте тип (один раз за время жизни клиента)
client.RegisterBinaryInsertType();
// Вставка напрямую — имена столбцов выводятся из имён свойств
var readings = Enumerable.Range(0, 100_000)
.Select(i => new SensorReading
{
Id = (ulong)i,
SensorName = $"sensor_{i % 10}",
Value = Random.Shared.NextDouble() * 100,
Timestamp = DateTime.UtcNow,
});
long rowsInserted = await client.InsertBinaryAsync("sensors", readings);
```
По умолчанию все общедоступные свойства, доступные для чтения, сопоставляются со столбцами по строгому совпадению имён с учётом регистра. Вы можете настроить это сопоставление с помощью атрибутов:
```csharp theme={null}
public class Event
{
[ClickHouseColumn(Name = "event_id")] // Сопоставить со столбцом с другим именем
public ulong Id { get; set; }
[ClickHouseColumn(Type = "LowCardinality(String)")] // Явный тип ClickHouse
public string Category { get; set; }
public string Payload { get; set; }
[ClickHouseNotMapped] // Исключить из вставки
public string InternalTag { get; set; }
}
```
| Атрибут | Назначение |
| ---------------------------------- | ----------------------------------- |
| `[ClickHouseColumn(Name = "...")]` | Переопределяет имя целевого столбца |
| `[ClickHouseColumn(Type = "...")]` | Явно задаёт тип ClickHouse |
| `[ClickHouseNotMapped]` | Исключает свойство из вставки |
Когда **все** сопоставленные свойства явно задают `Type`, запрос для определения схемы полностью пропускается. Если явные типы указаны только у части свойств, драйвер возвращается к запросу для определения схемы для полного набора столбцов.
`InsertBinaryAsync` поддерживает те же `InsertOptions` (батчинг, параллелизм, кэширование схемы), что и перегрузка `object[]`.
В отличие от перегрузки `object[]`, `InsertBinaryAsync` не принимает явный список столбцов. Столбцы определяются сопоставленными свойствами зарегистрированного типа. Чтобы управлять тем, какие столбцы вставляются, используйте `[ClickHouseNotMapped]`, чтобы исключить свойства, или `[ClickHouseColumn(Name = "...")]`, чтобы переименовать их.
Если в `InsertOptions` задан `ColumnTypes`, он имеет приоритет над атрибутами POCO.
#### Эволюция схемы
Вставка POCO работает без проблем, если после регистрации типа в целевую таблицу добавляются новые столбцы. Поскольку драйвер вставляет только те столбцы, которые сопоставлены с POCO, все новые столбцы с `DEFAULT` (или другими выражениями по умолчанию) сервер заполняет автоматически. Никаких изменений в коде или повторной регистрации не требуется.
***
### Чтение данных
Используйте `ExecuteReaderAsync` для выполнения SELECT-запросов. Возвращаемый `ClickHouseDataReader` предоставляет типизированный доступ к столбцам результата с помощью таких методов, как `GetInt64()`, `GetString()` и `GetFieldValue()`.
Вызовите `Read()`, чтобы перейти к следующей строке. Метод возвращает `false`, когда строк больше не осталось. К столбцам можно обращаться по индексу (с нуля) или по имени столбца.
```csharp theme={null}
using ClickHouse.Driver.ADO.Parameters;
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("max_id", 100L);
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM default.my_table WHERE id < {max_id:Int64}",
parameters
);
while (reader.Read())
{
Console.WriteLine($"Id: {reader.GetInt64(0)}, Name: {reader.GetString(1)}");
}
```
#### Чтение в POCO
Вместо чтения столбцов по индексу или имени можно направлять результаты запроса напрямую в собственные классы. Один раз зарегистрируйте тип в клиенте, а затем используйте `QueryAsync`:
```csharp theme={null}
// Define a POCO matching your result columns
public class SensorReading
{
public ulong Id { get; set; }
public DateTime Timestamp { get; set; }
[ClickHouseColumn(Name = "sensor_name")]
public string SensorName { get; set; }
public double Value { get; set; }
}
// Register the type (once per client lifetime)
client.RegisterPocoType();
// Stream results as typed objects
await foreach (var reading in client.QueryAsync(
"SELECT Id, sensor_name, Value, Timestamp FROM sensors"))
{
Console.WriteLine($"{reading.SensorName}: {reading.Value}");
}
```
##### Регистрация
`RegisterPocoType()` настраивает сопоставления как для вставки, так и для чтения, и заранее проверяет оба. `RegisterBinaryInsertType()` не изменился и по-прежнему используется только для вставки в целях обратной совместимости.
Зарегистрированный тип должен иметь:
* Публичный конструктор без параметров.
* Как минимум одно публичное свойство с публичным сеттером, не являющимся `init`. Свойства `required` поддерживаются.
##### Сопоставление столбцов
Сопоставление столбцов чувствительно к регистру. Если в результате отсутствуют столбцы, свойства сохраняют значения по умолчанию; лишние столбцы в результате игнорируются.
Автоматические преобразования отсутствуют, а несоответствие типов вызывает `InvalidOperationException`.
##### Материализация одной строки
При ручном переборе через reader используйте `ClickHouseDataReader.MapTo()`, чтобы материализовать текущую строку в зарегистрированный объект POCO, не продвигая reader дальше:
```csharp theme={null}
var reader = await client.ExecuteReaderAsync("SELECT Id, SensorName, Value, Timestamp FROM sensors");
while (reader.Read())
{
SensorReading reading = reader.MapTo();
Console.WriteLine($"{reading.SensorName}: {reading.Value}");
}
```
##### Диагностика регистрации
Если настроен `LoggerFactory`, `RegisterPocoType()` и `RegisterBinaryInsertType()` выводят сообщение журнала уровня `Debug` (категория `ClickHouse.Driver.Client`) со списком того, какие свойства сопоставлены с какими столбцами, а также какие были пропущены и почему. См. [Логирование и диагностика](#logging-and-diagnostics).
***
### Параметры SQL
В ClickHouse стандартный формат параметров в SQL-запросах — `{parameter_name:DataType}`.
**Примеры:**
```sql theme={null}
SELECT {value:Array(UInt16)} as a
```
```sql theme={null}
SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}
```
```sql theme={null}
INSERT INTO table VALUES ({val1:Int32}, {val2:Array(UInt8)})
```
SQL-параметры 'bind' передаются как параметры HTTP-запроса в URI, поэтому их слишком большое количество может привести к исключению "URL too long". Чтобы избежать этого ограничения при массовой вставке данных, используйте `InsertBinaryAsync`.
#### Параметры `Identifier`
Тип параметра `Identifier` позволяет безопасно подставлять имя базы данных, таблицы или столбца вместо строкового литерала в кавычках. Используйте его с помощью синтаксиса `{name:Identifier}` в SQL или задав `ClickHouseDbParameter.ClickHouseType = "Identifier"`:
```csharp theme={null}
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("name", "my_database");
await client.ExecuteNonQueryAsync("CREATE DATABASE {name:Identifier}", parameters);
```
```csharp theme={null}
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("col", "user_id");
var reader = await client.ExecuteReaderAsync("SELECT {col:Identifier} FROM t", parameters);
```
Значение передаётся как есть, а сервер подставляет его как обычный SQL-идентификатор, самостоятельно заключая в обратные кавычки и экранируя спецсимволы. Идентификаторы, содержащие специальные символы (включая обратные кавычки), безопасно проходят полный цикл преобразования.
***
### Query ID
Каждому запросу назначается уникальный `query_id`, который можно использовать, чтобы получить данные из таблицы `system.query_log` или отменить долго выполняющиеся запросы. Вы можете указать собственный идентификатор запроса через `QueryOptions`:
```csharp theme={null}
var options = new QueryOptions
{
QueryId = $"report-{Guid.NewGuid()}"
};
var reader = await client.ExecuteReaderAsync(
"SELECT * FROM large_table",
parameters: null,
options: options
);
```
Если вы задаёте собственный `QueryId`, убедитесь, что он уникален для каждого вызова. Хорошим выбором будет случайный GUID.
***
### Пользовательское сопоставление типов параметров
При использовании параметров в стиле `@` (например, `WHERE id = @id`) драйвер автоматически определяет тип ClickHouse по типу значения .NET. Например, `int` сопоставляется с `Int32`.
**Поведение для автоматически определяемых параметров `DateTime`**
Для параметров в стиле `@`, у которых в SQL нет подсказки `{name:Type}` и не задан `ClickHouseType`, значения, представляющие момент времени, определяются как `DateTime('UTC')`, а не как обычный `DateTime`. Значения `DateTime` с `Kind`, равным `Utc` или `Local`, а также все значения `DateTimeOffset` отправляются как `DateTime('UTC')`, что сохраняет момент времени при любом часовом поясе сервера.
Явные подсказки (`{name:DateTime}`) имеют приоритет над автоматическим определением и являются рекомендуемым способом построения запросов.
Чтобы переопределить эти значения по умолчанию, задайте `ParameterTypeResolver` в `ClickHouseClientSettings`. Это полезно, если вы хотите, чтобы все параметры `DateTime` использовали `DateTime64(3)` с точностью до миллисекунд, или чтобы для всех десятичных значений использовался определённый масштаб, без необходимости задавать `ClickHouseType` для каждого отдельного параметра.
**Использование `DictionaryParameterTypeResolver` для простых сопоставлений типов:**
```csharp theme={null}
using ClickHouse.Driver.ADO.Parameters;
var settings = new ClickHouseClientSettings("Host=localhost")
{
ParameterTypeResolver = new DictionaryParameterTypeResolver(new Dictionary
{
[typeof(DateTime)] = "DateTime64(3)",
[typeof(decimal)] = "Decimal64(4)",
}),
};
using var client = new ClickHouseClient(settings);
var parameters = new ClickHouseParameterCollection();
parameters.AddParameter("dt", DateTime.UtcNow); // Mapped to DateTime64(3)
parameters.AddParameter("amount", 99.1234m); // Mapped to Decimal64(4)
await client.ExecuteReaderAsync("SELECT @dt, @amount", parameters);
```
**Пользовательский `IParameterTypeResolver` для расширенных сценариев:**
Если нужно определять тип по значению или имени, реализуйте интерфейс `IParameterTypeResolver` напрямую. Верните `null`, чтобы использовать определение типа по умолчанию:
```csharp theme={null}
public class SmartDecimalResolver : IParameterTypeResolver
{
public string ResolveType(Type clrType, object value, string parameterName)
{
if (clrType != typeof(decimal))
return null; // Fall through to default
var scale = (decimal.GetBits((decimal)value)[3] >> 16) & 0x7F;
return scale <= 4 ? $"Decimal64({scale})" : $"Decimal128({scale})";
}
}
```
Вы также можете задать resolver для отдельного запроса через `QueryOptions.ParameterTypeResolver`. Если он задан, он имеет приоритет над resolver на уровне клиента.
**Приоритет разрешения типов:**
Resolver — это один из шагов в цепочке приоритетов. От наивысшего приоритета к наименьшему:
1. Явно заданный `ClickHouseType` у параметра
2. Подсказка типа SQL из синтаксиса `{name:Type}` в запросе
3. `IParameterTypeResolver` (из `QueryOptions.ParameterTypeResolver` с откатом к `ClickHouseClientSettings.ParameterTypeResolver`)
4. Встроенный вывод типов (`TypeConverter.ToClickHouseType`)
Resolver также работает с путём ADO.NET `ClickHouseConnection` — настройки наследуются соединениями, созданными клиентом.
***
### Пользовательское форматирование значений параметров
`IParameterFormatter` — это хук, который определяет, как сериализуются значения параметров. Используйте его, если встроенное форматирование (например, точность для DateTime, локаль для decimal, экранирование строк, представление чисел) не соответствует тому, что ожидают ваша схема или последующие инструменты.
Задайте `ParameterFormatter` в `ClickHouseClientSettings`, чтобы подключить форматтер для всех параметризованных запросов. Форматтер получает значение, разрешённое имя типа ClickHouse и имя параметра, а затем возвращает строковое представление, которое отправляется на сервер. Верните `null`, чтобы использовать форматтер по умолчанию.
**Использование `DictionaryParameterFormatter` для простого форматирования по типам CLR:**
```csharp theme={null}
using ClickHouse.Driver.ADO.Parameters;
var settings = new ClickHouseClientSettings("Host=localhost")
{
ParameterFormatter = new DictionaryParameterFormatter(new Dictionary>
{
[typeof(DateTime)] = v => ((DateTime)v).ToString("yyyy-MM-ddTHH:mm:ss.ffffff",
System.Globalization.CultureInfo.InvariantCulture),
[typeof(decimal)] = v => ((decimal)v).ToString("F4",
System.Globalization.CultureInfo.InvariantCulture),
}),
};
using var client = new ClickHouseClient(settings);
```
**Пользовательский `IParameterFormatter` для сложных сценариев:**
```csharp theme={null}
public class FixedDecimalFormatter : IParameterFormatter
{
public string Format(object value, string typeName, string parameterName)
{
if (value is decimal d)
return d.ToString("F4", System.Globalization.CultureInfo.InvariantCulture);
return null; // Fall through for anything else
}
}
```
Вы также можете задать форматтер для отдельного запроса через `QueryOptions.ParameterFormatter`. Если он задан, то имеет приоритет над форматтером на уровне клиента.
**Составные значения:**
Форматтер применяется как к параметрам-коллекциям верхнего уровня, так и к каждому элементу внутри составных значений (`Array`, `Tuple`, `Map`, `Nullable`, `LowCardinality`, `Variant`). Например, сопоставление `typeof(int)` форматирует каждый элемент `Int32` в `Array(Int32)` по отдельности.
**Оборачивание в одинарные кавычки в составных контекстах:**
Для строкоподобных типов ClickHouse (`String`, `FixedString`, `Enum8`, `Enum16`, `IPv4`, `IPv6`, `UUID`), встроенных в составной литерал, драйвер оборачивает вывод форматтера в одинарные кавычки, но не экранирует его содержимое. Если возвращаемая строка содержит неэкранированную одинарную кавычку или обратную косую черту, составной литерал будет некорректным, и сервер отклонит запрос.
Строковые параметры верхнего уровня (не встроенные в составной тип) используются как есть, без оборачивания, поэтому экранирование там не требуется.
**Приоритет форматтера:**
1. `IParameterFormatter` (из `QueryOptions.ParameterFormatter`, с переходом к `ClickHouseClientSettings.ParameterFormatter`). Если он возвращает не-NULL, используется это значение.
2. Встроенное форматирование для конкретных типов в `HttpParameterFormatter`.
Форматтер не вызывается для значений `null` или `DBNull`; они всегда сериализуются как null-маркер ClickHouse (`\N`).
***
### Пользовательское преобразование значений при чтении
`IReadValueConverter` позволяет преобразовывать значения, возвращаемые средством чтения данных после десериализации, не меняя их CLR-тип. Типичные сценарии использования: установка `DateTime.Kind = Utc` для столбца `DateTime` без timezone, обрезка или нормализация строк, а также постобработка JSON-столбца перед передачей в прикладной код.
Задайте `ReadValueConverter` в `ClickHouseClientSettings`, чтобы установить преобразователь для всех операций чтения. Преобразователь вызывается один раз для каждого столбца в каждой строке как через boxed-путь (`GetValue`), так и через обобщённый путь (`GetFieldValue`). Если преобразователь не задан, дополнительная нагрузка отсутствует — средство чтения возвращает значения напрямую.
**Использование `DictionaryReadValueConverter` для простого преобразования по CLR-типу:**
```csharp theme={null}
using ClickHouse.Driver.ADO.Readers;
var converter = new DictionaryReadValueConverter()
.For(dt => DateTime.SpecifyKind(dt, DateTimeKind.Utc))
.For(s => s.Trim());
var settings = new ClickHouseClientSettings("Host=localhost")
{
ReadValueConverter = converter,
};
using var client = new ClickHouseClient(settings);
```
Значения, тип CLR которых во время выполнения не зарегистрирован через `For`, передаются без изменений. Диспетчеризация выполняется по точному типу CLR, поэтому регистрируйте фактический тип, который возвращает reader (например, `For` для JSON-столбца в `JsonReadMode.Binary`).
**Пользовательский `IReadValueConverter` для продвинутых сценариев:**
Если вам нужно выполнять диспетчеризацию по строковому представлению типа на стороне ClickHouse (например, чтобы различать `DateTime` и `DateTime('UTC')` — хотя оба отображаются как один и тот же тип CLR), реализуйте `IReadValueConverter` напрямую:
```csharp theme={null}
public class UtcKindForNoTzDateTimeConverter : IReadValueConverter
{
public object ConvertValue(object value, string columnName, string clickHouseType)
{
if (value is DateTime dt && clickHouseType == "DateTime")
return DateTime.SpecifyKind(dt, DateTimeKind.Utc);
return value;
}
public T ConvertValue(T value, string columnName, string clickHouseType)
{
if (typeof(T) == typeof(DateTime) && value is DateTime dt && clickHouseType == "DateTime")
return (T)(object)DateTime.SpecifyKind(dt, DateTimeKind.Utc);
return value;
}
}
```
Конвертер должен сохранять CLR-тип времени выполнения; метаданные столбца (`GetFieldType`, `GetSchemaTable`) не перенаправляются через него и должны оставаться согласованными с возвращаемым значением.
Вы также можете задать конвертер для каждого запроса через `QueryOptions.ReadValueConverter`; если он задан, приоритет будет у него, а не у конвертера уровня клиента.
**Граница диспетчеризации:**
Конвертер вызывается один раз для каждого столбца и получает всё десериализованное значение ячейки целиком; он **не** выполняет рекурсивную обработку составных контейнеров. Для столбца `Array(Int32)` передаваемым значением будет `int[]`; для `Tuple(Int32, String)` — `ITuple`.
Конвертер работает с ADO.NET-путём `ClickHouseConnection` — настройки наследуются соединениями, созданными из клиента.
***
### Прямая потоковая передача
Используйте `ExecuteRawResultAsync`, чтобы напрямую передавать результаты запроса в указанном формате, минуя средство чтения данных. Это удобно для экспорта данных в файлы или передачи в другие системы:
```csharp theme={null}
using var result = await client.ExecuteRawResultAsync(
"SELECT * FROM default.my_table LIMIT 100 FORMAT JSONEachRow"
);
await using var stream = await result.ReadAsStreamAsync();
using var reader = new StreamReader(stream);
var json = await reader.ReadToEndAsync();
```
Распространённые форматы: `JSONEachRow`, `CSV`, `TSV`, `Parquet`, `Native`. Все доступные варианты см. в [документации по форматам](/docs/ru/reference/formats/index).
***
### Сжатие передачи для отдельного запроса
По умолчанию клиент согласовывает `gzip, deflate`, когда `Compression=true` (значение по умолчанию в строке подключения), а HTTP-клиент прозрачно распаковывает поток.
Для экспорта в исходном формате (например, Parquet, Arrow, Native) может потребоваться согласовать другой кодек (например, `zstd` или `lz4`), чтобы снизить нагрузку на CPU в обмен на пропускную способность, не меняя настройку для всего соединения. `QueryOptions.AcceptEncoding` и `ClickHouseCommand.AcceptEncoding` задают HTTP-заголовок `Accept-Encoding` для одного запроса, заменяя любое значение по умолчанию, и принудительно устанавливают `enable_http_compression=1` в URL (ClickHouse требует этого, чтобы учитывать `Accept-Encoding`).
```csharp theme={null}
using var result = await client.ExecuteRawResultAsync(
"SELECT * FROM events FORMAT Parquet",
options: new QueryOptions { AcceptEncoding = "zstd" });
// Decode yourself or write to a file
await using var body = await result.ReadAsStreamAsync();
```
#### Конфигурация HttpClient
`HttpClient`, который драйвер создает по умолчанию, имеет `AutomaticDecompression = GZip | Deflate`, поэтому данные, сжатые этими алгоритмами, распаковываются автоматически, а `Content-Encoding` удаляется из ответа. Для обычных запросов это именно то, что нужно, но не если вы хотите сами обрабатывать исходные сжатые данные.
В таком случае передайте в ClickHouseClient `HttpClient` или `HttpClientFactory` с `AutomaticDecompression = DecompressionMethods.None`
Если `AcceptEncoding` запрашивает кодек, который настроенный `HttpClient` не может распаковать автоматически, безопасно использовать только `ExecuteRawResultAsync`. Вызов `ExecuteReaderAsync`, `ExecuteScalarAsync` или `ExecuteNonQueryAsync` по тому же пути запроса попытается разобрать сжатые байты как обычный формат результата и вернет некорректные данные.
#### Тела ошибок
Когда сервер отвечает кодом 4xx/5xx и задан параметр `enable_http_compression=1`, он сжимает тело ошибки тем же кодеком, который использовал бы для успешного ответа. Драйвер распаковывает такие ответы для кодеков, входящих в BCL (`gzip`, `deflate`, `br`/`brotli`), поэтому сообщение, передаваемое в `ClickHouseServerException`, остаётся читаемым. Для кодеков, которые он не может декодировать (`zstd`, `lz4`, …), драйвер возвращает сообщение-заполнитель, в котором указан кодек и дана ссылка на `system.query_log`, где можно найти исходный текст ошибки.
***
### Вставка из необработанного потока
Используйте `InsertRawStreamAsync`, чтобы вставлять данные напрямую из файловых потоков или потоков в памяти в таких форматах, как CSV, JSON, Parquet, или в любом [поддерживаемом формате ClickHouse](/docs/ru/reference/formats/index).
**Вставка из CSV-файла:**
```csharp theme={null}
await using var fileStream = File.OpenRead("data.csv");
using var response = await client.InsertRawStreamAsync(
table: "my_table",
stream: fileStream,
format: "CSV",
columns: ["id", "product", "price"] // Optional: specify columns
);
```
Параметры, управляющие поведением ингестии данных, см. в [документации по настройкам форматов](/docs/ru/reference/settings/formats).
***
### Дополнительные примеры
Дополнительные практические примеры использования см. в каталоге [examples](https://github.com/ClickHouse/clickhouse-cs/tree/main/examples) репозитория GitHub.
## ADO.NET
Библиотека предоставляет полную поддержку ADO.NET через `ClickHouseConnection`, `ClickHouseCommand` и `ClickHouseDataReader`. Этот API необходим для интеграции с ORM (Dapper, Linq2db), а также в случаях, когда нужны стандартные абстракции базы данных .NET.
### Управление жизненным циклом с ClickHouseDataSource
**Всегда создавайте соединения через `ClickHouseDataSource`**, чтобы обеспечить корректное управление жизненным циклом и использование пула соединений. DataSource внутренне использует один `ClickHouseClient`, и все соединения совместно используют его пул HTTP-соединений.
```csharp theme={null}
using ClickHouse.Driver.ADO;
// Создать DataSource один раз (зарегистрировать как singleton в DI)
var dataSource = new ClickHouseDataSource("Host=localhost;Username=default;Password=secret");
// Создавать лёгкие соединения по мере необходимости
await using var connection = await dataSource.OpenConnectionAsync();
// Использовать соединение
await using var command = connection.CreateCommand("SELECT version()");
var version = await command.ExecuteScalarAsync();
```
При использовании внедрения зависимостей:
```csharp theme={null}
// В Startup.cs или Program.cs
services.AddSingleton(sp =>
{
var factory = sp.GetRequiredService();
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`.
**Рекомендуемые подходы:**
| Сценарий | Рекомендуемый подход |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| Общий случай | Используйте singleton `ClickHouseClient` |
| ADO.NET / ORM | Используйте `ClickHouseDataSource` (он создает соединения, использующие один и тот же пул) |
| Окружения с DI | Регистрируйте `ClickHouseClient` или `ClickHouseDataSource` как singleton через `IHttpClientFactory` |
При использовании пользовательского `HttpClient` или `HttpClientFactory` убедитесь, что для `PooledConnectionIdleTimeout` задано значение меньше, чем `keep_alive_timeout` сервера, чтобы избежать ошибок из-за полузакрытых соединений. Значение `keep_alive_timeout` по умолчанию для развертываний в Cloud составляет 10 секунд.
Не создавайте несколько экземпляров `ClickHouseClient` или автономных экземпляров `ClickHouseConnection` без общего `HttpClient`. Каждый экземпляр создает собственный пул соединений.
***
### Обработка DateTime
1. **По возможности используйте UTC.** Храните временные метки в столбцах `DateTime('UTC')` и используйте `DateTimeKind.Utc` в коде. Это устраняет неоднозначность, связанную с часовыми поясами.
2. **Используйте `DateTimeOffset` для явной работы с часовыми поясами.** Он всегда представляет конкретный момент времени и содержит информацию о смещении.
3. **Указывайте часовой пояс в подсказках типов SQL.** Если вы используете параметры со значениями DateTime `Unspecified` для столбцов не в 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
);
```
***
### Асинхронные вставки
[Асинхронные вставки](/docs/ru/concepts/features/operations/insert/asyncinserts) переносят ответственность за батчинг с клиента на сервер. Вместо батчинга на стороне клиента сервер буферизует входящие данные и сбрасывает их в хранилище при достижении настраиваемых пороговых значений. Это особенно полезно в сценариях с высоким параллелизмом, например для рабочих нагрузок обсервабилити, где множество агентов отправляют небольшие полезные нагрузки.
Включите асинхронные вставки через `CustomSettings` или строку подключения:
```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"
```
**Два режима** (управляются параметром `wait_for_async_insert`):
| Режим | Поведение | Сценарий использования |
| ------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `wait_for_async_insert=1` | Вставка завершается после того, как данные сбрасываются на диск. Ошибки возвращаются клиенту. | **Рекомендуется** для большинства рабочих нагрузок |
| `wait_for_async_insert=0` | Вставка завершается сразу после буферизации данных. Нет гарантии, что данные будут сохранены. | Только если допустима потеря данных |
При `wait_for_async_insert=0` ошибки проявляются только во время сброса на диск, и их нельзя связать с исходной вставкой. Кроме того, клиент не обеспечивает обратного давления, что создает риск перегрузки сервера.
**Ключевые настройки:**
| Настройка | Описание |
| ------------------------------- | ---------------------------------------------------------- |
| `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` |
***
#### Десятичные типы
| Тип 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.
***
#### Логический тип
| Тип ClickHouse | Тип .NET |
| -------------- | -------- |
| Bool | `bool` |
***
#### Строковые типы
| Тип ClickHouse | Тип .NET |
| -------------- | -------- |
| String | `string` |
| FixedString(N) | `string` |
По умолчанию столбцы `String` и `FixedString(N)` возвращаются как `string`. Установите `ReadStringsAsByteArrays=true` в строке подключения, чтобы вместо этого считывать их как `byte[]`. Это полезно при хранении бинарных данных, которые могут быть не в корректной кодировке UTF-8.
***
#### Типы даты и времени
| Тип ClickHouse | Тип .NET |
| -------------- | ---------- |
| Date | `DateTime` |
| Date32 | `DateTime` |
| DateTime | `DateTime` |
| DateTime32 | `DateTime` |
| DateTime64 | `DateTime` |
| Time | `TimeSpan` |
| Time64 | `TimeSpan` |
ClickHouse хранит значения `DateTime` и `DateTime64` внутри как Unix-временные метки (секунды или доли секунды с начала эпохи Unix). Хотя хранение всегда выполняется в UTC, со столбцами может быть связан часовой пояс, который влияет на то, как значения отображаются и интерпретируются.
При чтении значений `DateTime` свойство `DateTime.Kind` устанавливается на основе часового пояса столбца:
| Определение столбца | Возвращаемый DateTime.Kind | Примечания |
| ------------------------------ | -------------------------- | ------------------------------------ |
| `DateTime('UTC')` | `Utc` | Явно указан часовой пояс UTC |
| `DateTime('Europe/Amsterdam')` | `Unspecified` | Применяется смещение |
| `DateTime` | `Unspecified` | Локальное время сохраняется как есть |
Для столбцов не в UTC возвращаемый `DateTime` представляет локальное время в этом часовом поясе. Используйте `ClickHouseDataReader.GetDateTimeOffset()`, чтобы получить `DateTimeOffset` с корректным смещением для этого часового пояса:
```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`, а не `DateTime('Europe/Amsterdam')`) драйвер возвращает `DateTime` с `Kind=Unspecified`. Это позволяет сохранить локальное время в точности в том виде, в котором оно хранится, не делая предположений о часовом поясе.
Если для столбцов без явно заданных часовых поясов вам нужно поведение с учётом часового пояса, сделайте одно из следующего:
1. Используйте явные часовые пояса в определениях столбцов: `DateTime('UTC')` или `DateTime('Europe/Amsterdam')`
2. Задайте часовой пояс самостоятельно после чтения.
***
#### Тип JSON
| Тип ClickHouse | Тип .NET | Примечания |
| -------------- | ------------ | ------------------------------------ |
| 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`. Сохраняет точное представление JSON из ClickHouse, что полезно, когда JSON нужно передать дальше без парсинга или если вы хотите самостоятельно выполнять десериализацию.
```csharp theme={null}
// Настройка строкового режима через параметры
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[]` (вложенный `Array(Array(T))` читается как ступенчатый `T[][]`; используйте `reader.GetFieldValue(ordinal)` для материализации прямоугольных данных в виде многомерного массива CLR) |
| 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. В таблицах ниже показано, какие типы .NET допускаются для каждого типа столбца ClickHouse.
#### Целочисленные типы
| Тип 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-битный формат brain floating point с усечением |
***
#### Логический тип
| Тип ClickHouse | Допустимые типы .NET | Примечания |
| -------------- | -------------------- | ---------- |
| Bool | `bool` | |
***
#### Строковые типы
| Тип ClickHouse | Допустимые типы .NET | Примечания |
| -------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| String | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | Бинарные типы записываются напрямую; потоки могут поддерживать `seek` или не поддерживать его |
| FixedString(N) | `string`, `byte[]`, `ReadOnlyMemory`, `Stream` | Строка кодируется в UTF-8 и дополняется; бинарные типы должны содержать ровно N байт |
***
#### Типы даты и времени
| Тип ClickHouse | Допустимые типы .NET | Примечания |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Date | `DateTime`, `DateTimeOffset`, `DateOnly`, типы NodaTime | Преобразуется в дни Unix как UInt16; поддерживаемый диапазон `[1970-01-01, 2149-06-06]` |
| Date32 | `DateTime`, `DateTimeOffset`, `DateOnly`, типы NodaTime | Преобразуется в дни Unix как Int32; поддерживаемый диапазон `[1900-01-01, 2299-12-31]` |
| DateTime | `DateTime`, `DateTimeOffset`, `DateOnly`, типы NodaTime | Подробности см. ниже; поддерживаемый диапазон `[1970-01-01, 2106-02-07 06:28:15]` UTC |
| DateTime32 | `DateTime`, `DateTimeOffset`, `DateOnly`, типы NodaTime | То же, что и DateTime |
| DateTime64 | `DateTime`, `DateTimeOffset`, `DateOnly`, типы NodaTime | Точность зависит от параметра Scale |
| Time | `TimeSpan`, `int` | Ограничивается диапазоном ±999:59:59; `int` интерпретируется как секунды |
| Time64 | `TimeSpan`, `decimal`, `double`, `float`, `int`, `long`, `string` | Строка разбирается как `[-]HHH:MM:SS[.fraction]`; ограничивается диапазоном ±999:59:59.999999999 |
**Значения вне диапазона**
При записи по бинарному пути значения `Date`, `Date32`, `DateTime` и `DateTime32`, выходящие за пределы поддерживаемого диапазона, вызывают `ArgumentOutOfRangeException` во время `Write`, при этом указываются тип столбца и поддерживаемый диапазон. Ранее значения вне диапазона могли молча усекаться через 32-битное целое число и затем переинтерпретироваться сервером, что приводило к появлению реальных, но неверных временных меток.
Драйвер учитывает `DateTime.Kind` при записи значений:
| DateTime.Kind | HTTP-параметры | Пакетная вставка |
| ------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Utc | Точный момент времени сохраняется | Точный момент времени сохраняется |
| Local | Точный момент времени сохраняется | Точный момент времени сохраняется |
| Unspecified | Интерпретируется как локальное время в часовом поясе типа параметра (по умолчанию UTC) | Интерпретируется как локальное время в часовом поясе столбца |
Значения `DateTimeOffset` всегда сохраняют точный момент времени.
**Пример: UTC DateTime (точный момент времени сохраняется)**
```csharp theme={null}
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
```
**Пример: DateTime без указания часового пояса (время по местным часам)**
```csharp theme={null}
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
```
**Рекомендация:** для максимально простого и предсказуемого поведения используйте `DateTimeKind.Utc` или `DateTimeOffset` во всех операциях с DateTime. Это гарантирует, что ваш код будет работать одинаково независимо от часового пояса сервера, клиента или столбца.
#### HTTP-параметры vs пакетная загрузка
При записи значений DateTime с `Unspecified` есть важное различие между привязкой HTTP-параметров и пакетной загрузкой:
**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-параметр (с указанием часового пояса) | HTTP-параметр (без указания часового пояса) | Пакетная загрузка |
| --------------- | ---------------- | ------------------------------------------ | ------------------------------------------- | ------------------------------------- |
| `Utc` | UTC | Точный момент времени сохраняется | Точный момент времени сохраняется | Точный момент времени сохраняется |
| `Utc` | Europe/Amsterdam | Точный момент времени сохраняется | Точный момент времени сохраняется | Точный момент времени сохраняется |
| `Local` | Любой | Точный момент времени сохраняется | Точный момент времени сохраняется | Точный момент времени сохраняется |
| `Unspecified` | UTC | Интерпретируется как UTC | Интерпретируется как UTC | Интерпретируется как UTC |
| `Unspecified` | Europe/Amsterdam | Интерпретируется как время Амстердама | **Интерпретируется как UTC** | Интерпретируется как время Амстердама |
***
#### Десятичные типы
| Тип 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. На стороне клиента данные преобразуются в двоичный JSON-формат ClickHouse с полной поддержкой подсказок типов. Перед использованием необходимо вызвать `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 можно записывать в JSON-столбцы двумя способами в зависимости от `JsonWriteMode`:
**Режим String (по умолчанию)**: POCO сериализуются через `System.Text.Json.JsonSerializer`. Регистрировать типы не требуется. Это самый простой вариант, и он работает с анонимными объектами.
**Бинарный режим**: POCO сериализуются с использованием бинарного JSON-формата драйвера с полной поддержкой подсказок типа. Перед использованием типы необходимо зарегистрировать с помощью `connection.RegisterJsonSerializationType()`. Этот режим поддерживает пользовательские сопоставления путей с помощью атрибутов:
* **`[ClickHouseJsonPath("path")]`**: Связывает свойство с пользовательским JSON-путём. Полезно для вложенных структур или когда имя свойства отличается от нужного JSON-ключа. **Работает только в бинарном режиме.**
* **`[ClickHouseJsonIgnore]`**: Исключает свойство из сериализации. **Работает только в бинарном режиме.**
```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`. Это соответствует поведению ClickHouse, где пути вроде `userName` и `UserName` могут сосуществовать как отдельные поля.
**Ограничения (только для режима Binary):**
* Типы POCO должны быть зарегистрированы для подключения с помощью `connection.RegisterJsonSerializationType()` до сериализации. Попытка сериализовать незарегистрированный тип вызывает исключение `ClickHouseJsonSerializationException`.
* Для корректной сериализации свойств словарей и массивов/списков требуются подсказки типов в определении столбца. Без таких подсказок используйте режим String.
* Значения NULL в свойствах POCO записываются только в том случае, если для пути в определении столбца указана подсказка типа `Nullable(T)`. ClickHouse не допускает типы `Nullable` внутри динамических JSON-путей, поэтому свойства со значением null без подсказок пропускаются.
* Атрибуты `ClickHouseJsonPath` и `ClickHouseJsonIgnore` игнорируются в режиме String (они работают только в режиме Binary).
***
#### Другие типы
| Тип ClickHouse | Допустимые типы .NET | Примечания |
| ----------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UUID | `Guid`, `string` | Строка преобразуется в `Guid` |
| IPv4 | `IPAddress`, `string` | Должен быть IPv4; строка разбирается с помощью `IPAddress.Parse()` |
| IPv6 | `IPAddress`, `string` | Должен быть IPv6; строка разбирается с помощью `IPAddress.Parse()` |
| Nothing | Any | Ничего не записывает (no-op) |
| Dynamic | — | **Не поддерживается** (генерирует `NotImplementedException`) |
| Array(T) | `IList`, `null` | При `null` записывается пустой массив. Для вложенных типов (`Array(Array(T))` и глубже) поддерживаются как ступенчатые массивы (`T[][]`, `List>`), так и прямоугольные многомерные массивы CLR (`T[,]`, `T[,,]`, …); ранг CLR должен соответствовать глубине вложенности ClickHouse. |
| Tuple(T1, T2, ...) | `ITuple`, `IList` | Число элементов должно соответствовать арности кортежа. Для случаев с более чем 7 элементами см. [оговорку о ValueTuple](#valuetuple-caveat). |
| Map(K, V) | `IDictionary` | |
| Nullable(T) | `null`, `DBNull`, или типы, допустимые для T | Перед значением записывается байт флага null |
| Enum8 | `string`, `sbyte`, числовые типы | Для строки выполняется поиск в словаре enum |
| Enum16 | `string`, `short`, числовые типы | Для строки выполняется поиск в словаре 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 | `IList` из точек | |
| LineString | `IList` из точек | |
| Polygon | `IList` из колец | |
| MultiLineString | `IList` из объектов LineString | |
| MultiPolygon | `IList` из объектов Polygon | |
| 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` | Начало/завершение выполнения запроса, время выполнения, идентификаторы запросов, статистика сервера и сведения об ошибках. |
| `ClickHouse.Driver.Transport` | `ClickHouseConnection` | Низкоуровневые запросы для потоковой передачи по HTTP, флаги сжатия, коды состояния ответа и ошибки транспорта. |
| `ClickHouse.Driver.Client` | `ClickHouseClient` | Бинарная вставка, запросы и другие операции |
| `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
* События открытия и закрытия соединения
* Отслеживание идентификатора сеанса
### Режим отладки: сетевая трассировка и диагностика
Чтобы упростить диагностику сетевых проблем, библиотека драйвера содержит вспомогательный механизм, который включает низкоуровневую трассировку внутренних механизмов сетевой подсистемы .NET. Чтобы включить его, необходимо передать LoggerFactory с установленным уровнем Trace и задать EnableDebugMode = true (или включить его вручную через класс `ClickHouse.Driver.Diagnostic.TraceHelper`). События будут записываться в категорию `ClickHouse.Driver.NetTrace`. Предупреждение: это приведет к созданию чрезвычайно подробных журналов и повлияет на производительность. Включать режим отладки в продакшн не рекомендуется.
```csharp theme={null}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddConsole()
.SetMinimumLevel(LogLevel.Trace); // Необходим уровень Trace для отображения сетевых событий
});
var settings = new ClickHouseClientSettings()
{
LoggerFactory = loggerFactory,
EnableDebugMode = true, // Включить низкоуровневую трассировку сети
};
```
## OpenTelemetry
Драйвер поддерживает встроенную распределённую трассировку OpenTelemetry через API .NET [`System.Diagnostics.Activity`](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing). При включении драйвер создаёт спаны для операций с базой данных, которые можно экспортировать в системы обсервабилити, такие как Jaeger или сам ClickHouse (через [OpenTelemetry Collector](/docs/ru/guides/use-cases/observability/build-your-own/integrating-opentelemetry)).
### Включение трассировки
В приложениях ASP.NET Core добавьте `ActivitySource` драйвера ClickHouse в конфигурацию OpenTelemetry:
```csharp theme={null}
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddSource(ClickHouseDiagnosticsOptions.ActivitySourceName) // Подписка на spans драйвера 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-операторы в spans (по умолчанию: false из соображений безопасности)
ClickHouseDiagnosticsOptions.IncludeSqlInActivityTags = true;
// Усекать длинные SQL-операторы (по умолчанию: 1000 символов)
ClickHouseDiagnosticsOptions.StatementMaxLength = 500;
```
Включение `IncludeSqlInActivityTags` может привести к раскрытию конфиденциальных данных в трассировках. Используйте с осторожностью в продакшн-средах.
## Настройка TLS
При подключении к ClickHouse по HTTPS поведение TLS/SSL можно настроить несколькими способами.
### Пользовательская проверка сертификатов
Для продакшн-окружений, в которых требуется пользовательская логика проверки сертификатов, передайте собственный `HttpClient` с настроенным обработчиком `ServerCertificateCustomValidationCallback`:
```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` сервера (10 секунд для ClickHouse Cloud), чтобы избежать ошибок подключения из-за полуоткрытых соединений.
## Поддержка ORM
Для ORM требуется API ADO.NET (`ClickHouseConnection`). Чтобы корректно управлять временем жизни подключения, создавайте подключения через `ClickHouseDataSource`:
```csharp theme={null}
// Зарегистрировать DataSource как singleton
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.
Используйте `ClickHouseDataSource` для корректного управления временем жизни соединения:
```csharp theme={null}
var dataSource = new ClickHouseDataSource("Host=localhost");
services.AddSingleton(dataSource); // Зарегистрировать как singleton в 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);
```
**Словарь:**
```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
Если вам нужен явный контроль над типами, используйте непосредственно в SQL синтаксис ClickHouse `{param:Type}`, а значения параметров передавайте через `Dictionary`. Не используйте синтаксис `@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)`, а драйвер обрабатывает каждый развёрнутый параметр.
**Функция `has()` в ClickHouse с параметром `Array` тоже работает:**
```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);
```
#### Пользовательские обработчики типов
Для некоторых типов ClickHouse, например `ITuple`, `BigInteger` и `ClickHouseDecimal`, необходимо зарегистрировать обработчики при запуске:
```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`, `[]`). Вместо него рекомендуется использовать нативный метод `InsertBinaryAsync` клиента `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);
```
Имена свойств должны в точности совпадать с именами столбцов ClickHouse (с учетом регистра).
#### Ограничения
| Что | Статус | Подробности |
| ---------------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| Tuple как **результат** | Работает | Требуется регистрация `SqlMapper.TypeHandler` |
| Tuple как **параметр** | Не поддерживается | Dapper не может сериализовать `ITuple`/`Tuple<>` в качестве значения `DbParameter` |
| Вложенные типы как параметры | Не поддерживается | По той же причине — Dapper отклоняет сложные типы в качестве значений параметров |
| Гео-типы как параметры | Не поддерживается | Point, Ring, Polygon, LineString, MultiLineString, MultiPolygon |
| `Dapper.Contrib.Insert()` | Не поддерживается | Генерирует синтаксис, специфичный для SQL Server |
| Тип `Nothing` | Не поддерживается | В .NET нет осмысленного представления |
### Linq2db
Этот драйвер совместим с [linq2db](https://github.com/linq2db/linq2db) — легковесным ORM и LINQ-провайдером для .NET. Подробную документацию см. на сайте проекта.
**Пример использования:**
Создайте `DataConnection`, используя провайдер 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);
```
Сопоставление таблиц можно задать с помощью атрибутов или Fluent-конфигурации. Если имена класса и его свойств в точности совпадают с именами таблицы и столбцов, конфигурация не требуется:
```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
Официальный провайдер Entity Framework Core для ClickHouse. Сопоставляйте классы C# с таблицами ClickHouse, выполняйте запросы с помощью LINQ и добавляйте данные через `SaveChanges` — всё это в привычных шаблонах EF Core.
* **NuGet**: [`ClickHouse.EntityFrameworkCore`](https://www.nuget.org/packages/ClickHouse.EntityFrameworkCore)
* **Source**: [GitHub](https://github.com/ClickHouse/ClickHouse.EntityFrameworkCore)
Этот провайдер активно развивается. Текущая версия поддерживает LINQ-запросы (включая JOIN, подзапросы и операции над множествами), `INSERT` через `SaveChanges` / `BulkInsertAsync`, миграции с полной поддержкой DDL (CREATE / ALTER / DROP), а также настройку движка таблицы ClickHouse. `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(P,S)`, `Decimal32(S)`, `Decimal64(S)`, `Decimal128(S)` | `decimal` или `ClickHouseDecimal` |
| **Bool** | `Bool` | `bool` |
| **Строки** | `String`, `FixedString(N)` | `string` |
| **Перечисления** | `Enum8(...)`, `Enum16(...)` | `string` или C# `enum` |
| **Дата/время** | `Date`, `Date32`, `DateTime`, `DateTime64(P, 'TZ')` | `DateOnly`, `DateTime` |
| **Время** | `Time`, `Time64(N)` | `TimeSpan` |
| **UUID** | `UUID` | `Guid` |
| **Сетевые типы** | `IPv4`, `IPv6` | `IPAddress` |
| **Массивы** | `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` и их массивы; `object` для Geometry |
| **Обёртки** | `Nullable(T)`, `LowCardinality(T)` | Автоматически разворачиваются |
Используйте `ClickHouseDecimal` (из `ClickHouse.Driver.Numerics`) вместо `decimal`, если нужна полная точность столбцов `Decimal128`/`Decimal256`: `decimal` в .NET ограничен 28–29 значащими цифрами.
#### Поддерживаемые операции LINQ
**Запросы:** `Where`, `OrderBy`, `Take`, `Skip`, `Select`, `First`, `Single`, `Any`, `All`, `Count`, `Distinct`, `AsNoTracking`
**GROUP BY и агрегатные функции:** `GroupBy` с `Count`, `LongCount`, `Sum`, `Average`, `Min`, `Max` — включая `HAVING` (`.Where()` после `.GroupBy()`), несколько агрегатных функций в одной проекции и `OrderBy` по результатам агрегации.
**JOIN:** `Join` (INNER), шаблоны `GroupJoin`/`SelectMany` (LEFT и CROSS). LEFT JOIN возвращает реальный `null` для строк без совпадений (см. [семантику NULL в LEFT JOIN](#ef-core-join-nulls) ниже).
**Подзапросы:** коррелированные `Contains` / `IN`, `Any` / `EXISTS`, `All`, а также скалярные подзапросы в проекциях.
**Операции над множествами:** `Concat` (→ `UNION ALL`), `Union` (→ `UNION DISTINCT`), `Intersect`, `Except`.
**Встроенные локальные коллекции:** JOIN и `Contains` с коллекциями в памяти (`int[]`, `List` и т. д.) преобразуются в последовательность UNION.
**Строковые методы:** `Contains`, `StartsWith`, `EndsWith`, `IndexOf`, `Replace`, `Substring`, `Trim`/`TrimStart`/`TrimEnd`, `ToLower`, `ToUpper`, `Length`, `IsNullOrEmpty`, `Concat` (и оператор `+`).
**Математические функции:** стандартные методы `Math` и `MathF`, преобразуемые в эквивалентные функции ClickHouse — арифметические, логарифмические, тригонометрические и вспомогательные функции.
##### Семантика NULL в LEFT JOIN
Провайдер автоматически добавляет `set_join_use_nulls=1` во все подключения, чтобы поведение JOIN соответствовало ожиданиям Entity Framework.
Если ваш сервер ClickHouse или профиль запрещает изменять эту настройку (например, профиль `readonly=1`), отключите это поведение с помощью:
```csharp theme={null}
optionsBuilder.UseClickHouse(connectionString, o => o.DisableJoinNullSemantics());
```
При включенном opt-out LEFT JOIN возвращает значения столбцов ClickHouse по умолчанию, и механизм определения навигации по null в EF больше не работает должным образом. Используйте явные сравнения с `0` / `""` вместо `== null`.
#### Вставка данных
`SaveChanges` использует нативный API драйвера `InsertBinaryAsync` — кодирование 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();
```
Сущности после сохранения переходят из состояния `Added` в `Unchanged`, как и у любого другого поставщика EF Core.
**Размер батча** можно настроить (по умолчанию — 1000):
```csharp theme={null}
optionsBuilder.UseClickHouse("Host=localhost", o => o.MaxBatchSize(5000));
```
#### Пакетная вставка
Для высоконагруженной вставки данных используйте `BulkInsertAsync` вместо `SaveChanges`. Это метод расширения для `DbContext`, который полностью обходит механизм отслеживания изменений EF Core, разрешение идентичности и управление состоянием — он напрямую вызывает `InsertBinaryAsync` драйвера с двоичным кодированием RowBinary и сжатием GZip.
Поэтому он хорошо подходит для загрузки больших наборов данных, когда после вставки отслеживание сущностей не требуется:
```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();
```
#### Пользовательские преобразования типов
Система `ValueConverter` в EF Core позволяет сопоставлять пользовательские типы с типами, которые уже поддерживает провайдер. Сам провайдер ваш пользовательский тип не видит — 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; }
}
```
**Использование fluent API в `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)");
});
```
Поддерживаются вложенные обёртки, такие как `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-столбцы
Провайдер поддерживает тип столбца `Json` в ClickHouse, сопоставляя его с `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 не транслируются** — `entity.Data["name"]` в LINQ не преобразуется в SQL-синтаксис ClickHouse `data.name`. Фильтруйте по не-JSON-столбцам и анализируйте JSON в памяти.
* **Семантика NULL** — JSON type в ClickHouse возвращает `{}` (пустой объект) для значений NULL, а не SQL NULL.
* **Точность целых чисел** — ClickHouse хранит все целые числа в JSON как `Int64`. При чтении через `JsonNode` используйте `GetValue()`, а не `GetValue()`.
#### Движки таблиц
Настраивайте движки таблиц ClickHouse и специфичные для движка секции через fluent API `ToTable(name, t => ...)`. Если движок не настроен, провайдер по умолчанию использует `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")` или `HasReplacingMergeTreeEngine(e => e.Version)` | Столбцы Version / IsDeleted необязательны |
| `SummingMergeTree` | `HasSummingMergeTreeEngine(…)` или `HasSummingMergeTreeEngine(e => new { … })` | Необязательные суммируемые столбцы |
| `AggregatingMergeTree` | `HasAggregatingMergeTreeEngine()` | — |
| `CollapsingMergeTree` | `HasCollapsingMergeTreeEngine("Sign")` или `HasCollapsingMergeTreeEngine(e => e.Sign)` | Столбец `Sign` должен иметь тип `Int8` |
| `VersionedCollapsingMergeTree` | `HasVersionedCollapsingMergeTreeEngine("Sign", "Version")` или `(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, кодеки/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 для принадлежащих сущностей пока не реализовано. Вместо этого используйте `JsonNode` / `string` в столбце `Json` (см. [JSON-столбцы](#ef-core-json)). |
Помимо миграций, провайдер также пока не поддерживает:
* **`UPDATE` / `DELETE`**
* **Транзакции**: `BeginTransaction` — no-op. ClickHouse не поддерживает ACID-транзакции.
* **Трансляцию запросов с JSON-путём**: `entity.Data["key"]` в LINQ не транслируется в SQL-синтаксис ClickHouse `data.key`. Фильтруйте по не-JSON-столбцам, а JSON анализируйте в памяти.
## Ограничения
### Tuple из 8+ элементов с вложенным кортежем на последней позиции
Типы C# `ValueTuple`, содержащие более 7 элементов, используют схему вложенности, генерируемую компилятором: 8-й универсальный аргумент (`TRest`) сам является `ValueTuple`, содержащим оставшиеся элементы. Например, `(int, int, int, int, int, int, int, string, string)` компилируется в `ValueTuple>`.
Из-за этого возникает неоднозначность, когда столбец ClickHouse представляет собой 8-элементный кортеж, у которого последний элемент сам является кортежем — например, `Tuple(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Tuple(String, String))`. Драйвер не может различить:
* **Плоский 9-элементный кортеж** (вложенность TRest, сгенерированная компилятором)
* **8-элементный кортеж**, у которого последний элемент — вложенный `Tuple(String, String)`
В обоих случаях получается один и тот же тип .NET: `ValueTuple>`.
Драйвер обрабатывает 8-й аргумент как TRest (то есть разворачивает его), а значит, случай с 8 элементами и вложенным кортежем будет сериализован некорректно.
Это затрагивает как `System.Tuple`, так и `ValueTuple`, поскольку оба используют вложенность TRest для случаев с более чем 7 элементами. Tuple с 7 или меньшим числом элементов, а также кортежи, у которых последний элемент сам по себе не является кортежем, этой проблеме не подвержены.
**Обходной путь:** оберните внутренний кортеж в дополнительный слой, чтобы драйвер мог отличить его от вложенности TRest:
```csharp theme={null}
// Instead of this (ambiguous — is it 8 elements or 9 flat?):
Tuple.Create(1, 2, 3, 4, 5, 6, 7, Tuple.Create("a", "b"))
// Do this (unambiguous — inner tuple is wrapped):
Tuple.Create(1, 2, 3, 4, 5, 6, 7, Tuple.Create(Tuple.Create("a", "b")))
```
***
### Столбцы AggregateFunction
Столбцы типа `AggregateFunction(...)` нельзя запрашивать или напрямую вставлять в них данные.
Чтобы выполнить вставку:
```sql theme={null}
INSERT INTO t VALUES (uniqState(1));
```
Чтобы выбрать:
```sql theme={null}
SELECT uniqMerge(c) FROM t;
```
***