ClickHouse.Ado 1.2.1

.NET driver for Yandex ClickHouse. It implements native ClickHouse protocol with data compression (not a wrapper for HTTP client)

There is a newer version of this package available.
See the version list below for details.
Install-Package ClickHouse.Ado -Version 1.2.1
dotnet add package ClickHouse.Ado --version 1.2.1
<PackageReference Include="ClickHouse.Ado" Version="1.2.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ClickHouse.Ado --version 1.2.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: ClickHouse.Ado, 1.2.1"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install ClickHouse.Ado as a Cake Addin
#addin nuget:?package=ClickHouse.Ado&version=1.2.1

// Install ClickHouse.Ado as a Cake Tool
#tool nuget:?package=ClickHouse.Ado&version=1.2.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

ClickHouse.ADO

.NET driver for Yandex ClickHouse. This driver implements native ClickHouse protocol, shamelessly ripped out of original ClickHouse sources. In some ways it does not comply to ADO.NET
rules however this is intentional.

А ещё есть описание по-русски, см. ниже.

Important usage notes

No multiple queries

ClickHouse engine does not support parsing multiple queries per on IDbCommand.Execute* roundtrip. Please split your queries into separately executed commands.

Always use NextResult

Although you may think that NextResult would not be used due to aforementioned lack of multiple query support that's completely wrong! You must always use NextResult
as ClickHouse protocol and engine may and will return multiple resultsets per query and sometime result schemas may differ (definetly in regard to field
ordering if query doesn't explicitly specify it).

Hidden bulk-insert functionality

If you read ClickHouse documentation it stongly advices you to insert records in bulk (1000+ per request). This driver can do bulk inserts. To do so you have to use special
insert syntax:

INSERT INTO some_table (col1, col2, col3) VALUES @bulk

And after that you must add parameted named bulk with its Value castable to IEnumerable each item of it must be IEnumerable too. Empty lists are not allowed.
Alternatively you may pass IBulkInsertEnumerable implementation as a bulk's value to speed up processing and use less memory inside clickhouse driver.
This may be used conviniently with the following syntax:

CREATE TABLE test (date Date, time DateTime, str String, int UInt16) ENGINE=MergeTree(date,(time,str,int), 8192)
class MyPersistableObject:IEnumerable{
	public string MyStringField;
	public DateTime MyDateField;
	public int MyIntField;

	//Count and order of returns must match column order in SQL INSERT
	public IEnumerator GetEnumerator(){
		yield return MyDateField;
		yield return MyDateField;
		yield return MyStringField;
		yield return (ushort)MyIntField;
	}
}

//... somewhere elsewhere ...
var list=new List<MyPersistableObject>();

// fill the list to insert
list.Add(new MyPersistableObject());

var command=connection.CreateCommand();
command.CommandText="INSERT INTO test (date,time,str,int) VALUES @bulk";
command.Parameters.Add(new ClickHouseParameter{
	ParameterName="bulk",
	Value=list
});
command.ExecuteNonQuery();

Extending and deriving

If you've fixed some bugs or wrote some useful addition to this driver, please, do pull request them back here.

If you need some functionality or found a bug but unable to implement/fix it, please file a ticket here, on GitHub.

ClickHouse.ADO по-русски

.NET драйвер для Yandex ClickHouse. В отличие от официального JDBC клиента этот драйвер не является обёрткой поверх ClickHouse HTTP, а реализует нативный протокол. Протокол (и части его реализации) нагло выдраны из исходников самого ClickHouse. В некоторых случаях этот драйвер ведёт себя не так, как обычные ADO.NET драйверы, это сделано намеренно и связано со спецификой ClickHouse.

Прочти это перед использованием

Нет поддержки нескольких запросов

Движок ClickHouse не умеет обрабатывать несколько SQL запросов за один вызов IDbCommand.Execute*. Запросы надо разбивать на отдельные команды.

Всегда используй NextResult

В связи с вышесказаным может показаться что NextResult не нужен, но это совершенно не так. Использование NextResult обязательно, поскольку протокол и движок ClickHouse может и будет возвращать несколько наборов данных на один запрос, и, хуже того, схемы этих наборов могут различаться (по крайней мере может быть перепутан порядок полей, если запрос не имеет явного указания порядка).

Секретная функция групповой вставки

В документации ClickHouse указано, что вставлять данные лучше пачками 100+ записей. Для этого предусмотрен специальный синтаксис:

INSERT INTO some_table (col1, col2, col3) VALUES @bulk

Для этой команды надо задать параметр bulk со значением Value приводимым к IEnumerable, каждый из элементов которого, в свою очередь, тоже должен быть IEnumerable.
Кроме того, в качестве значения параметра bulk передать объект реализующий IBulkInsertEnumerable - это уменьшит использование памяти и процессора внутри драйвера clickhouse.
Это удобно при использовании такого синтаксиса:

CREATE TABLE test (date Date, time DateTime, str String, int UInt16) ENGINE=MergeTree(date,(time,str,int), 8192)
class MyPersistableObject:IEnumerable{
	public string MyStringField;
	public DateTime MyDateField;
	public int MyIntField;

	//Количество и порядок return должны соответствовать количеству и порядку полей в SQL INSERT
	public IEnumerator GetEnumerator(){
		yield return MyDateField;
		yield return MyDateField;
		yield return MyStringField;
		yield return (ushort)MyIntField;
	}
}

//... где-то ещё ...
var list=new List<MyPersistableObject>();

// заполнение списка вставляемых объектов
list.Add(new MyPersistableObject());

var command=connection.CreateCommand();
command.CommandText="INSERT INTO test (date,time,str,int) VALUES @bulk";
command.Parameters.Add(new ClickHouseParameter{
	ParameterName="bulk",
	Value=list
});
command.ExecuteNonQuery();

Расширение и наследование

Если вы исправили баг или реализовали какую-то фичу, пожалуйста, сделайте pull request в этот репозиторий.

Если вам не хватает какой-то функции или вы нашли баг, который не можете исправить, напишите тикет здесь, на GitHub.

ClickHouse.ADO

.NET driver for Yandex ClickHouse. This driver implements native ClickHouse protocol, shamelessly ripped out of original ClickHouse sources. In some ways it does not comply to ADO.NET
rules however this is intentional.

А ещё есть описание по-русски, см. ниже.

Important usage notes

No multiple queries

ClickHouse engine does not support parsing multiple queries per on IDbCommand.Execute* roundtrip. Please split your queries into separately executed commands.

Always use NextResult

Although you may think that NextResult would not be used due to aforementioned lack of multiple query support that's completely wrong! You must always use NextResult
as ClickHouse protocol and engine may and will return multiple resultsets per query and sometime result schemas may differ (definetly in regard to field
ordering if query doesn't explicitly specify it).

Hidden bulk-insert functionality

If you read ClickHouse documentation it stongly advices you to insert records in bulk (1000+ per request). This driver can do bulk inserts. To do so you have to use special
insert syntax:

INSERT INTO some_table (col1, col2, col3) VALUES @bulk

And after that you must add parameted named bulk with its Value castable to IEnumerable each item of it must be IEnumerable too. Empty lists are not allowed.
Alternatively you may pass IBulkInsertEnumerable implementation as a bulk's value to speed up processing and use less memory inside clickhouse driver.
This may be used conviniently with the following syntax:

CREATE TABLE test (date Date, time DateTime, str String, int UInt16) ENGINE=MergeTree(date,(time,str,int), 8192)
class MyPersistableObject:IEnumerable{
	public string MyStringField;
	public DateTime MyDateField;
	public int MyIntField;

	//Count and order of returns must match column order in SQL INSERT
	public IEnumerator GetEnumerator(){
		yield return MyDateField;
		yield return MyDateField;
		yield return MyStringField;
		yield return (ushort)MyIntField;
	}
}

//... somewhere elsewhere ...
var list=new List<MyPersistableObject>();

// fill the list to insert
list.Add(new MyPersistableObject());

var command=connection.CreateCommand();
command.CommandText="INSERT INTO test (date,time,str,int) VALUES @bulk";
command.Parameters.Add(new ClickHouseParameter{
	ParameterName="bulk",
	Value=list
});
command.ExecuteNonQuery();

Extending and deriving

If you've fixed some bugs or wrote some useful addition to this driver, please, do pull request them back here.

If you need some functionality or found a bug but unable to implement/fix it, please file a ticket here, on GitHub.

ClickHouse.ADO по-русски

.NET драйвер для Yandex ClickHouse. В отличие от официального JDBC клиента этот драйвер не является обёрткой поверх ClickHouse HTTP, а реализует нативный протокол. Протокол (и части его реализации) нагло выдраны из исходников самого ClickHouse. В некоторых случаях этот драйвер ведёт себя не так, как обычные ADO.NET драйверы, это сделано намеренно и связано со спецификой ClickHouse.

Прочти это перед использованием

Нет поддержки нескольких запросов

Движок ClickHouse не умеет обрабатывать несколько SQL запросов за один вызов IDbCommand.Execute*. Запросы надо разбивать на отдельные команды.

Всегда используй NextResult

В связи с вышесказаным может показаться что NextResult не нужен, но это совершенно не так. Использование NextResult обязательно, поскольку протокол и движок ClickHouse может и будет возвращать несколько наборов данных на один запрос, и, хуже того, схемы этих наборов могут различаться (по крайней мере может быть перепутан порядок полей, если запрос не имеет явного указания порядка).

Секретная функция групповой вставки

В документации ClickHouse указано, что вставлять данные лучше пачками 100+ записей. Для этого предусмотрен специальный синтаксис:

INSERT INTO some_table (col1, col2, col3) VALUES @bulk

Для этой команды надо задать параметр bulk со значением Value приводимым к IEnumerable, каждый из элементов которого, в свою очередь, тоже должен быть IEnumerable.
Кроме того, в качестве значения параметра bulk передать объект реализующий IBulkInsertEnumerable - это уменьшит использование памяти и процессора внутри драйвера clickhouse.
Это удобно при использовании такого синтаксиса:

CREATE TABLE test (date Date, time DateTime, str String, int UInt16) ENGINE=MergeTree(date,(time,str,int), 8192)
class MyPersistableObject:IEnumerable{
	public string MyStringField;
	public DateTime MyDateField;
	public int MyIntField;

	//Количество и порядок return должны соответствовать количеству и порядку полей в SQL INSERT
	public IEnumerator GetEnumerator(){
		yield return MyDateField;
		yield return MyDateField;
		yield return MyStringField;
		yield return (ushort)MyIntField;
	}
}

//... где-то ещё ...
var list=new List<MyPersistableObject>();

// заполнение списка вставляемых объектов
list.Add(new MyPersistableObject());

var command=connection.CreateCommand();
command.CommandText="INSERT INTO test (date,time,str,int) VALUES @bulk";
command.Parameters.Add(new ClickHouseParameter{
	ParameterName="bulk",
	Value=list
});
command.ExecuteNonQuery();

Расширение и наследование

Если вы исправили баг или реализовали какую-то фичу, пожалуйста, сделайте pull request в этот репозиторий.

Если вам не хватает какой-то функции или вы нашли баг, который не можете исправить, напишите тикет здесь, на GitHub.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on ClickHouse.Ado:

Package Downloads
ClickHouse.Net
Provides abstractions and helpers for ClickHouse.Ado.
CJENetworkLogger
.NET-based framework for building client-server applications
Qoollo.ClickHouse.Net
.NET library for ClickHouse with useful classes such as aggregating queue for bulk inserts. The ClickHouse-Net driver is used (native ClickHouse protocol with data compression).
Serilog.Sinks.ClickHouse
Write serilog events to clickhouse database.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.3.1 885 3/11/2021
1.2.6 13,993 10/27/2020
1.2.5 2,999 10/19/2020
1.2.4 2,122 9/16/2020
1.2.3 2,715 8/31/2020
1.2.2 1,776 8/25/2020
1.2.1 7,603 4/13/2020
1.2.0-preview-02 348 3/19/2020
1.2.0-preview-01 212 3/19/2020
1.1.21 11,522 2/4/2020
1.1.20 19,551 9/30/2019
1.1.19 1,151 9/23/2019
1.1.17 30,146 6/5/2019
1.1.16 338 5/30/2019
1.1.15 29,734 5/23/2019
1.1.13 13,590 1/28/2019
1.1.9 29,220 7/9/2018
1.1.7 588 7/5/2018
1.1.6 1,610 5/12/2018
1.1.5 16,160 11/27/2017
1.1.4 530 11/7/2017
1.1.3 513 11/3/2017
1.1.2 2,868 8/28/2017
1.1.1 802 6/21/2017
1.1.0 551 6/21/2017
1.0.2 604 6/2/2017
1.0.1 581 5/29/2017
1.0.0 691 4/26/2017
Show less