RepoDb.ClickHouse.BulkOperations 0.0.1-alpha1

RepoDb.ClickHouse.BulkOperations

A high-performant extension library of RepoDB that does bulk operations towards a ClickHouse database. It uses its own internal class ClickHouseBulkCopy to load the data towards the database, built on top of ClickHouse.Driver's native ClickHouseBulkCopy streaming-insert implementation.

Important Pages

• GitHub Home — core library and source code.
• Website — full documentation, API reference, and blog.

Core Features

• Async Methods
• BulkInsert
• BulkMerge
• BulkUpdate
• BulkDelete
• BulkDeleteByKey

Community

• GitHub Issues — bug reports and feature requests.
• Microsoft Teams — live Q&A.
• GitHub Discussions — ask questions and share ideas.
• X / Twitter — news and updates.

License

Apache-2.0 — Copyright © 2026 Michael Camara Pendon

Installation

Install-Package RepoDb.ClickHouse.BulkOperations

Then call the setup for ClickHouse.

RepoDb
    .Setup()
    .UseClickHouse();

Waiting for mutations: BulkMerge/BulkUpdate/BulkDelete/BulkDeleteByKey all resolve to ClickHouse's asynchronous ALTER TABLE ... UPDATE/DELETE mutations under the hood, applied by a background merge rather than immediately - a query issued right after one of these calls returns is not guaranteed to see the change yet. Pass isWaitForMutationsEnabled: true to UseClickHouse() (it defaults to false) to have these operations block until each mutation actually finishes (up to a 5-second timeout) before returning, trading extra latency per call for read-your-writes consistency. This is read from ClickHouseDbSetting.IsWaitForMutationsEnabled on the mapped IDbSetting - see the RepoDb.ClickHouse README for details.

Async Methods

Every synchronous operation has a corresponding Async overload.

BulkInsert

Inserts a list of entities into the database in bulk. Returns the number of inserted rows.

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var insertedRows = connection.BulkInsert<Customer>(customers);
}

Or via table-name:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var insertedRows = connection.BulkInsert("Customer", customers);
}

Or via a DataTable:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var table = GetCustomersAsDataTable();
    var insertedRows = connection.BulkInsert("Customer", table);
}

Note: Unlike the SQL Server/MySQL/Oracle providers, ClickHouse has no identity, auto-increment, or sequence mechanism of any kind, so ClickHouseBulkImportIdentityBehavior.ReturnIdentity is not supported here - passing it throws a NotSupportedException. Use KeepIdentity (the default) instead, and assign your own key values before inserting.

BulkMerge

Upserts a list of entities in bulk — inserts new rows and updates existing ones based on the defined qualifiers. Returns the number of affected rows.

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var mergedRows = connection.BulkMerge<Customer>(customers);
}

Or with qualifiers:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var mergedRows = connection.BulkMerge<Customer>(customers, qualifiers: e => new { e.LastName, e.DateOfBirth });
}

Or via table-name with qualifiers:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var mergedRows = connection.BulkMerge("Customer", customers, qualifiers: Field.From("LastName", "DateOfBirth"));
}

Or via a DataTable:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var table = GetCustomersAsDataTable();
    var mergedRows = connection.BulkMerge("Customer", table);
}

BulkUpdate

Updates existing rows in the database in bulk, matched by the defined qualifiers. Returns the number of updated rows.

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var rows = connection.BulkUpdate<Customer>(customers);
}

Or with qualifiers:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var rows = connection.BulkUpdate<Customer>(customers, qualifiers: e => new { e.LastName, e.DateOfBirth });
}

Or via a DataTable:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var table = GetCustomersAsDataTable();
    var rows = connection.BulkUpdate("Customer", table);
}

BulkDelete

Deletes existing rows from the database in bulk, matched by the defined qualifiers. Returns the number of deleted rows.

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var deletedRows = connection.BulkDelete<Customer>(customers);
}

Or with qualifiers:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var customers = GetCustomers();
    var deletedRows = connection.BulkDelete<Customer>(customers, qualifiers: e => new { e.LastName, e.DateOfBirth });
}

Or via a DataTable:

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var table = GetCustomersAsDataTable();
    var deletedRows = connection.BulkDelete("Customer", table);
}

BulkDeleteByKey

Deletes existing rows from the database in bulk, matched by their primary (or identity) key value alone — no entities or DataTable involved, just the list of key values to remove. Returns the number of deleted rows.

using (var connection = new ClickHouseConnection(ConnectionString))
{
    var primaryKeys = new [] { 10045, 10046, 10047 };
    var deletedRows = connection.BulkDeleteByKey("Customer", primaryKeys);
}

License

Apache License 2.0 — Copyright © 2026 Michael Camara Pendon

This project depends on ClickHouse.Driver (the ADO.NET driver for ClickHouse, formerly known as ClickHouse.Client), which is separately licensed under the MIT License.