СВОБОДНОЕ ПО

В составе Сфера MDX сервер работает драйвер ClickHouse собственной разработки с открытым исходным кодом

Драйвер ClickHouse собственной разработки

Все обращения Сфера MDX сервер к хранилищу на ClickHouse выполняются через драйвер Octonica.ClickHouseClient, разработанный нашей компанией. Это реализация драйвера ClickHouse для .NET в виде провайдера ADO.NET, которая работает по бинарному протоколу ClickHouse и поддерживает все возможности ADO.NET, кроме транзакций.

Драйвер используется в промышленной эксплуатации. Его исходный код открыт и распространяется по лицензии Apache-2.0: любой разработчик на .NET может подключить драйвер к своему проекту, изучить реализацию и участвовать в развитии.

Собственный драйвер даёт серверу то, что важно для многомерного анализа: передачу временных таблиц вместе с запросом (например, списка ролей пользователя), передачу контекста трассировки в ClickHouse, пакетную запись больших объёмов данных и поддержку актуальных версий ClickHouse и платформы .NET.

Apache-2.0

лицензия, исходный код открыт

ADO.NET

стандартный API для .NET

4.1.6

текущая версия

NuGet

Octonica.ClickHouseClient

GitHub NuGet Журнал изменений

Основные возможности

Точкой входа драйвера служит стандартный для ADO.NET класс подключения. Поэтому код, написанный для других драйверов ADO.NET, переносится на ClickHouse с минимальными изменениями.

Бинарный протокол

Прямая работа по нативному протоколу ClickHouse без промежуточного HTTP-слоя.

Сжатие данных

Сжатие при отправке и при получении данных сокращает сетевой трафик.

Часовые пояса

Поддержка часовых поясов для типов DateTime и DateTime64.

Полный асинхронный API

Все операции ADO.NET доступны в асинхронном виде, включая чтение результата.

Без unsafe-кода

Драйвер написан целиком на управляемом коде, без небезопасных конструкций.

Кортежи и record

Поддержка именованных кортежей и record языка C#.

Параметры запросов

Параметры в формате {имя:Тип} и @имя, а также передача целых таблиц вместе с запросом.

Пакетная запись

Запись большого числа строк по столбцам через ClickHouseColumnWriter.

Трассировка OpenTelemetry

Передача идентификаторов трассировки в ClickHouse: запрос включается в общую цепочку вызовов.

Настройки запроса

Параметры ClickHouse можно задавать для каждого запроса отдельно.

Режим занятого подключения

Поведение при обращении к занятому подключению: ожидание или немедленная ошибка.

Dapper и Linq To DB

Совместимость с популярными библиотеками доступа к данным.

Типы данных ClickHouse

Поддерживается большинство типов столбцов. Соответствие типов ClickHouse и типов .NET описано в документации драйвера.

Int8 … Int256UInt8 … UInt256Float32, Float64DecimalDate, Date32DateTime, DateTime64String, FixedStringUUIDIPv4, IPv6Enum8, Enum16NullableArrayTupleMapLowCardinality

Описание API

Основные классы драйвера находятся в пространстве имён Octonica.ClickHouseClient. Классы ADO.NET наследуют стандартные базовые классы, поэтому знакомые методы работают привычным образом.

Класс	Назначение	Основные члены
`ClickHouseConnection`	Подключение к серверу. Точка входа ADO.NET, наследник DbConnection.	`Open / OpenAsyncCreateCommandCreateColumnWriter / CreateColumnWriterAsyncTryPingServerVersionGetServerTimeZone`
`ClickHouseConnectionStringBuilder`	Построение строки подключения из кода: Host=…;Port=…;Database=…;Password=….	`HostPortDatabaseUserPasswordCompressTlsModeCommandTimeoutBusyConnectionMode`
`ClickHouseCommand`	Команда: текст запроса, параметры, клиентские таблицы, настройки и трассировка.	`ParametersTableProvidersSettingsActivityQueryIdCancelExecuteReader / ExecuteScalar / ExecuteNonQuery`
`ClickHouseDataReader`	Построчное чтение результата запроса в синхронном и асинхронном режиме.	`Read / ReadAsyncGetValueGetFieldValue<T>GetString, GetInt32, GetGuid, GetDecimal …`
`ClickHouseParameter`	Параметр запроса. Тип определяется по значению и может быть задан явно.	`ClickHouseDbTypeIsNullablePrecision, Scale, SizeArrayRankTimeZone`
`ClickHouseTableProvider`	Таблица, формируемая на клиенте и передаваемая вместе с запросом. Реализует IClickHouseTableProvider.	`AddColumn`
`ClickHouseColumnWriter`	Запись произвольно большого числа строк в таблицу в столбцовом виде.	`WriteTable / WriteTableAsyncWriteRow / WriteRowAsyncGetOrdinalConfigureColumnEndWrite / EndWriteAsync`
`ClickHouseException, ClickHouseServerException`	Ошибки драйвера и ошибки, возвращённые сервером ClickHouse. Находятся в пространстве имён Octonica.ClickHouseClient.Exceptions.	`ErrorCodeServerErrorCodeServerErrorTypeQuery`

Документация

Parameters — параметры запросов и таблицы-параметры.
ClickHouseColumnWriter — пакетная запись строк.
TypeMapping — соответствие типов ClickHouse и .NET.
CHANGELOG — история версий.

Примеры использования

Установка пакета: dotnet add package Octonica.ClickHouseClient. Примеры показывают суть каждой возможности и в основном взяты из документации драйвера и из кода Сфера MDX сервер.

Подключение собирается из параметров или из строки. Запрос выполняется стандартными методами ADO.NET.

var builder = new ClickHouseConnectionStringBuilder { Host = "127.0.0.1" };
await using var connection = new ClickHouseConnection(builder);
await connection.OpenAsync();

var user = await connection.CreateCommand("SELECT currentUser()").ExecuteScalarAsync();

По материалам документации драйвера.

Свяжитесь с нами

Стоимость программного обеспечения рассчитывается индивидуально. По вопросам приобретения Сфера MDX сервер обращайтесь по электронной почте или просто позвоните.

Написать Позвонить