Table of Contents

Class ClickHouseDataContext

Namespace
NextORM.ClickHouse
Assembly
nextorm.clickhouse.dll

Data context for ClickHouse. Wraps the ClickHouse.Driver ADO.NET driver for connections and parameters and renders SQL through ClickHouseDialect.

public class ClickHouseDataContext : DataContext, IDataContext, IQueryExecutor, IQueryMaterializer, IQueryPlanner, IRowReaderFactory, IQueryCache, IContextEnvironment, IRawCommandExecutor, IAsyncDisposable, IDisposable, IConnectionManager, ITransactionManager
Inheritance
ClickHouseDataContext
Implements
Inherited Members
Extension Methods

Remarks

The bulk-insert executor is re-implemented here (the base hook cannot carry the whole-invocation budget or the explicit option presence) so BulkInsertMode resolves against the native InsertBinaryAsync prerequisites, the session/parallelism request is validated before a row is read, and the portable path is entered only for the equivalent single-stream request.

Constructors

ClickHouseDataContext(ClickHouseDataSource, DataContextBuilder)

Creates a ClickHouse context over a caller-supplied data source, which the context does not dispose: the pooled client is obtained from the data source and its settings are copied for the context's own connection, never mutated. This is an unversioned construction path.

public ClickHouseDataContext(ClickHouseDataSource dataSource, DataContextBuilder optionsBuilder)

Parameters

dataSource ClickHouseDataSource

An already-created ClickHouseDataSource owned by the caller.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

ClickHouseDataContext(ClickHouseClient, DataContextBuilder)

Creates a ClickHouse context over a caller-supplied client, which the context does not dispose. The context's own connection is built from a copy of the client's settings, so both share the same actual session id and every other setting; the caller's settings object is never mutated. This (like the data-source overload) is an unversioned construction path: a versioned capability must be declared through the versioned connection-string or connection constructor.

public ClickHouseDataContext(ClickHouseClient client, DataContextBuilder optionsBuilder)

Parameters

client ClickHouseClient

An already-created ClickHouseClient owned by the caller.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

ClickHouseDataContext(DbConnection, DataContextBuilder)

Creates a ClickHouse context over a caller-supplied connection, which the context does not dispose.

public ClickHouseDataContext(DbConnection connection, DataContextBuilder optionsBuilder)

Parameters

connection DbConnection

An already-created DbConnection owned by the caller.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

ClickHouseDataContext(string, DataContextBuilder)

Creates a ClickHouse context that owns a connection built lazily from connectionString.

public ClickHouseDataContext(string connectionString, DataContextBuilder optionsBuilder)

Parameters

connectionString string

The connection string used to create the ClickHouseConnection.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

ClickHouseDataContext(Version, DbConnection, DataContextBuilder)

Creates a ClickHouse context bound to an explicitly declared server version over a caller-supplied connection, which the context does not dispose.

public ClickHouseDataContext(Version serverVersion, DbConnection connection, DataContextBuilder optionsBuilder)

Parameters

serverVersion Version

The ClickHouse server version this context declares.

connection DbConnection

An already-created DbConnection owned by the caller.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

Exceptions

ArgumentNullException

serverVersion is null; use the unversioned constructor instead.

InvalidOperationException

A different capability declaration was already registered for this context type.

ClickHouseDataContext(Version, string, DataContextBuilder)

Creates a ClickHouse context bound to an explicitly declared server version that owns a connection built lazily from connectionString. The version is a caller declaration (there is no server probing): it enables the capabilities introduced after the pinned baseline (currently the native arrayExcept, ClickHouse 25.9).

public ClickHouseDataContext(Version serverVersion, string connectionString, DataContextBuilder optionsBuilder)

Parameters

serverVersion Version

The ClickHouse server version this context declares.

connectionString string

The connection string used to create the ClickHouseConnection.

optionsBuilder DataContextBuilder

The options collected from DataContextBuilder.

Exceptions

ArgumentNullException

serverVersion is null; use the unversioned constructor instead.

InvalidOperationException

A different capability declaration was already registered for this context type.

Properties

Dialect

SQL dialect used to render queries. Supplied by the provider; SQL generation depends on this interface rather than on the context itself.

public override ISqlDialect Dialect { get; }

Property Value

ISqlDialect

TimeOnlyProjectionRefusal

ClickHouse has no time-of-day type: the binder stores a TimeOnly as String, so a mapped projection would have to parse the text back. The projection is refused and a value converter must opt in explicitly.

protected override string? TimeOnlyProjectionRefusal { get; }

Property Value

string

Methods

CreateDbConnection(string?)

Creates the context's own ClickHouseConnection: from the connection string when the context was built with one, otherwise from a copy of the supplied client/data-source settings so the connection and the client address the same database and session.

protected override DbConnection CreateDbConnection(string? connectionString)

Parameters

connectionString string

The connection string, or null when settings were supplied.

Returns

DbConnection

A new, unopened ClickHouse connection.

CreateParam(string, object?)

Creates a ClickHouseDbParameter. The driver rewrites the ADO-style @name placeholder to {name:Type} and infers the ClickHouse type from the CLR value, so the stored name omits the @ prefix. A JsonObject, and an object-root JsonElement/JsonDocument, are bound as the native ClickHouse JSON type; a rank-1 CLR array whose declared element type is nullable (Nullable<T> or string) is bound as Array(Nullable(T)) so its null elements survive the driver's non-nullable inference. Any other value keeps its existing binding.

public override DbParameter CreateParam(string name, object? value)

Parameters

name string

The parameter name, without the provider prefix.

value object

The parameter value, or null.

Returns

DbParameter

A new ClickHouse parameter.

CreateProcedureParameter(ProcedureParameter)

Creates a ClickHouseDbParameter for a descriptor. A TableParameterValue is emulated with a native array expanded server-side with arrayJoin(@p): a scalar row type binds as an Array(T) and an entity row type as an Array(Tuple(...)) whose tuple elements follow the resolved column order. A TypeName is SQL Server only and is rejected.

protected override DbParameter CreateProcedureParameter(ProcedureParameter parameter)

Parameters

parameter ProcedureParameter

The parameter descriptor.

Returns

DbParameter

A new ClickHouse parameter configured from parameter.

Exceptions

ArgumentException

TypeName is set (SQL Server only), or a table parameter is not Input.

NotSupportedException

A table parameter column has a CLR type with no ClickHouse mapping.

Dispose(bool)

Releases the connection owned by the context and raises Disposed. Called from Dispose(); disposing is true for managed cleanup.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true when invoked from Dispose().

MapColumnExpression(SelectExpression, Expression)

Materializes a projected native ClickHouse JSON column. A bare JsonObject is read as-is; a bare JsonDocument/JsonElement is adapted from the driver's object-root JsonObject transport. A SQL NULL becomes a null reference (or default for the value-type JsonElement), which stays distinct from an empty object. A DateTimeOffset projection is adapted from the driver's DateTime transport (see MapDateTimeOffsetColumn(SelectExpression, Expression)). Every other column is mapped by the base implementation, which also resolves a [JsonColumn] converter (its provider type is JsonObject on ClickHouse).

public override Expression MapColumnExpression(SelectExpression column, Expression param)

Parameters

column SelectExpression

The projected column being read.

param Expression

The data-reader expression the accessor is built from.

Returns

Expression

An expression that reads the column value.

Edit this page