本文字数12722估计阅读时间32分钟作者Alex Soffronow Pagonidis编者按本文译自 ClickHouse 原博客链接点文末-查看原文。 原文围绕「相关技术主题」展开。 文章梳理了驱动在插入、读取和参数路径上的实际变化POCO 工作流是其中最值得关注的体验升级。对仍停留在 1.0 的用户来说这是一份清晰的迁移参考。今年 2 月我们发布了 .NET 驱动的首个稳定版本。该版本重点增强了类型支持、打包方式、配置及可观测性并引入了一套独立于旧版 ADO.NET API 的全新主 API。此后我们陆续发布了三个次版本在优化用户体验的同时不断增强客户端的扩展性与可配置性并进一步丰富了支持的数据类型。此外我们还开发了多项 .NET 生态集成。这些进展离不开社区的贡献感谢在此期间提交 Issue、复现 Bug 或提交 PR 的每一位开发者特别感谢 Daniel Bunting、Vyacheslav Brevnov、Minh Vu、Ozan Hanedan 以及 Musa Musaev。如果你对该驱动的印象还停留在 1.0 版本那么现在的写入、读取及参数处理流程均已显著进化。具体变化如下。基于 POCO 的类型安全工作流这是开发体验上最显著的一项改进。在 1.0 版本中常规操作依赖object[]。现在无论是读取还是写入都可以直接使用自定义类之前 (1.0)手动转换的 object[]using var client new ClickHouseClient(Hostlocalhost); // You own the column list, the ordering, and the boxing. await client.InsertBinaryAsync( sensors, new[] { Id, SensorName, Value, RecordedAt }, readings.Select(r new object[] { r.Id, r.SensorName, r.Value, r.RecordedAt }));以前每次写入都要重复声明表结构。一旦string[]中的列顺序写错就会引发运行时序列化错误甚至导致数据被悄无声息地错位写入。现在 (1.3)一次注册直接读写自定义类型public class SensorReading { public ulong Id { get; set; } public string SensorName { get; set; } public double Value { get; set; } public DateTime RecordedAt { get; set; } } using var client new ClickHouseClient(Hostlocalhost); client.RegisterPocoTypeSensorReading(); // sets up insert read, validates both up front // Write long rows await client.InsertBinaryAsync(sensors, readings); // IEnumerableSensorReading // Read await foreach (var r in client.QueryAsyncSensorReading( SELECT * FROM sensors WHERE Value 20;)) { Console.WriteLine(${r.SensorName}: {r.Value:F2}); }类型注册在初始化阶段完成它会校验类结构并尽早拦截映射问题。由于 Getter 和 Setter 经过预编译查询时几乎没有额外开销。QueryAsyncT返回IAsyncEnumerableT支持数据行的延迟实例化。当枚举结束、报错或中途break时读取器会自动释放。以下是几条匹配规则• 列匹配区分大小写 StringComparer.Ordinal 。• 若结果集中的列没有对应的类属性该列将被忽略。• 若类中的属性没有对应的结果列该属性将保持默认值。• 类型需要一个公共无参构造函数以及至少一个带公共非 init setter 的公共属性。支持 required 属性。映射属性你还可以使用特性来控制每个属性的列和类型映射public class AuditEvent { [ClickHouseColumn(Name event_id)] public ulong Id { get; set; } [ClickHouseColumn(Name event_type, Type LowCardinality(String))] public required string Type { get; set; } [ClickHouseNotMapped] public string InternalCorrelationTag { get; set; } }驱动程序不会进行任何隐式转换。如果类型不匹配会抛出InvalidOperationException并详细说明 POCO 类型、属性、列名以及实际返回的 CLR 类型方便快速定位。为了辅助调试映射器还提供了详细日志。只要配置了LoggerFactory注册时就会输出Debug级别的日志类别为ClickHouse.Driver.Client列出属性与列的映射关系、被跳过的属性及其原因。查看日志通常比查阅文档规则更高效。将 POCO 存入 JSON 列这一特性同样适用于 ClickHouse 的JSON类型。配合RegisterJsonSerializationTypeT()以及[ClickHouseJsonPath(...)]/[ClickHouseJsonIgnore]你可以直接将 POCO 写入 JSON 列并保持类型精度需将 JsonWriteMode 设为 Binarypublic class SensorAttributes { [ClickHouseJsonPath(device.id)] public required string DeviceId { get; set; } public decimal Temperature { get; set; } [ClickHouseJsonIgnore] public string LocalDebugTag { get; set; } } using var client new ClickHouseClient(Hostlocalhost;JsonWriteModeBinary); client.RegisterJsonSerializationTypeSensorAttributes(); // attributes JSON(device.id String, Temperature Decimal64(4)) await client.InsertBinaryAsync(readings, [id, attributes], [[1UL, new SensorAttributes { DeviceId sensor-7, Temperature 21.4375m }]]);写入后的数据行为{Temperature:21.4375,device:{id:sensor-7}}。端到端自定义流水线第二个重点是控制权。虽然驱动程序提供了合理的默认值但无法覆盖所有场景。为了让开发者更灵活地控制客户端行为我们新增了三个扩展点分别负责类型解析、参数序列化以及读取时的值转换。这些扩展点均为可选不使用时不会产生额外开销。接口阶段引入版本IParameterTypeResolverCLR 类型 → ClickHouse 类型1.2IParameterFormatter值 → 传输格式1.3IReadValueConverter传输值 → 返回时的 CLR 值1.3这三个接口都可以在ClickHouseClientSettings全局客户端级别或QueryOptions单次查询级别中进行配置。1. IParameterTypeResolver控制类型推断ClickHouse 要求发往服务端的参数带有类型声明例如{name:Type}。不过驱动也支持无类型的 ADO.NET 风格参数如WHERE id id这也是 Dapper 等 ORM 常用的形式。此时驱动必须根据 CLR 值推断 ClickHouse 类型。内置的推断策略倾向于保守decimal映射为Decimal128(scale)DateTime映射为DateTime(UTC)以最大限度减少信息丢失。但如果你的表结构统一使用Decimal64(4)和DateTime64(3)这种保守策略反而会报错迫使你在代码中为每个参数手动添加注解。通过IParameterTypeResolver你可以全局定义映射约定。针对常见场景驱动提供了一个内置的字典实现var settings new ClickHouseClientSettings(Hostlocalhost) { ParameterTypeResolver new DictionaryParameterTypeResolver(new DictionaryType, string { [typeof(decimal)] Decimal64(4), [typeof(DateTime)] DateTime64(3), }), };如果逻辑需要根据具体数值或参数名进行判断可以直接实现该接口。例如下面的代码会根据传入的具体值选择能容纳它的最窄 decimal 类型private class SmartDecimalResolver : IParameterTypeResolver { public string ResolveType(Type clrType, object value, string parameterName) { if (clrType ! typeof(decimal)) return null; // let everything else use default inference var scale (decimal.GetBits((decimal)value)[3] 16) 0x7F; return scale 4 ? $Decimal64({scale}) : $Decimal128({scale}); } }如果返回null驱动会退回到默认推断逻辑因此解析器只需处理特定情况即可。2. IParameterFormatter控制传输格式仅解析出类型有时还不够因为即使类型正确格式化输出rendering也可能不符合预期。HTTP 参数以文本形式发送驱动需要决定如何序列化每个值。这通常没有争议但也有例外例如DateTime列会接收带有亚秒精度的值并直接截断你可能希望在本地显式处理这种截断而不是交给服务端处理。var settings new ClickHouseClientSettings(Hostlocalhost) { ParameterFormatter new DictionaryParameterFormatter(new DictionaryType, Funcobject, string { // e.g. clamp to whole seconds regardless of the columns declared precision [typeof(DateTime)] v ((DateTime)v).ToString(yyyy-MM-dd HH:mm:ss, CultureInfo.InvariantCulture), }), };值得注意的两点• 无论是顶层值还是复合类型 Array 、 Tuple 、 Map 、 Nested 内部的元素都会调用该格式化器。• 透明包装器 Nullable 、 LowCardinality 、 Variant 会被预先解包因此格式化器只需处理底层具体类型。此外格式化器不会处理 null 或 DBNull 它们会被统一序列化为 ClickHouse 的空值占位符。3. IReadValueConverter在返回数据时进行标准化第三个接口用于处理数据返回。假设查询的DateTime列未指定时区读取到的值Kind属性通常为Unspecified。如果应用约定“所有时间戳均为 UTC”你可以在数据离开驱动前完成转换避免在业务代码中到处调用DateTime.SpecifyKindvar settings new ClickHouseClientSettings(Hostlocalhost) { ReadValueConverter new DictionaryReadValueConverter() .ForDateTime(dt DateTime.SpecifyKind(dt, DateTimeKind.Utc)) .Forstring(s s.Trim()), };该转换器会拦截GetValue()和GetFieldValueT()并在 POCO 实例化时生效因此QueryAsyncT()也会得到转换后的值。注意DictionaryReadValueConverter仅按CLR类型匹配而DateTime和DateTime(UTC)在 C# 中都表现为System.DateTime因此上述代码也会影响已带时区的列。如果需要区分请实现该接口并根据 ClickHouse 返回的类型名称进行逻辑分支此时获取的数据与服务器原始报告完全一致private class UtcOnlyForNoTzDateTimeConverter : IReadValueConverter { public object ConvertValue(object value, string columnName, string clickHouseType) value is DateTime dt clickHouseType DateTime ? DateTime.SpecifyKind(dt, DateTimeKind.Utc) : value; public T ConvertValueT(T value, string columnName, string clickHouseType) typeof(T) typeof(DateTime) value is DateTime dt clickHouseType DateTime ? (T)(object)DateTime.SpecifyKind(dt, DateTimeKind.Utc) : value; }该接口有两个限制• 不得改变值的运行时类型。 列元数据 GetFieldType 等不会根据转换器的输出重新推导。它并非数据映射层。• 不会递归处理复合类型。 它针对每行每列调用一次传入完整的已反序列化单元格数据例如对于 Array(Int32) 列你获取到的是完整的 int[] 。提供泛型重载是为了保证热路径性能通过 typeof(T) 检查配合 Unsafe.As 即可在不装箱的情况下直接转换值类型。更细粒度的配置项秉承同样的理念我们还优化了一些配置细节• 单次查询设置 Accept-Encoding QueryOptions.AcceptEncoding 对应 ClickHouseCommand.AcceptEncoding 可覆盖单个请求默认的 gzip, deflate 编码。此操作会强制设置 enable_http_compression1 以确保服务端生效。 请注意如果使用 BCL 无法解码的压缩格式如 zstd、lz4必须在 HttpClient 中设置 AutomaticDecompression None 并通过 ExecuteRawResultAsync 读取响应体。具体编码可通过 ClickHouseRawResult.ContentEncoding 获取。• GetFieldValueT(string name) 支持按列名获取数据作为按索引获取的补充。• ApplicationInfo ClickHouseClientSettings 新增了自定义标签字典 IReadOnlyDictionarystring, string 如 app 、 ver 、 env 等。这些标签会以注释形式附加在 HTTP User-Agent 标头中例如 (app:MyApp; ver:2.3.1; env:prod) 。这在通过数据库查询日志追溯来源时非常有用。更丰富的类型支持我们持续优化了 CLR 与 ClickHouse 之间的类型映射新增了对多维数组、ValueTuples 以及 Identifier 参数的支持。嵌套与多维数组感谢 DanielBunting 的贡献现在可以将Array(Array(T))及更深层嵌套作为多维数组读写。C# 支持两种 N 维数组交错数组int[][]数组的数组行长可变和矩形数组int[,]连续内存行长固定。ClickHouse 的Array(Array(T))在结构上对应交错数组。但在处理矩形数据时强制使用交错数组会增加额外的对象分配。现在写入操作已同时支持交错数组T[][]、ListListT和矩形数组T[,]、T[,,]等。读取时默认仍为交错格式但GetFieldValueT[,]可以直接实例化为矩形数组并校验形状。// Write: jagged or rectangular, your choice int[][] jagged [[1, 2], [3], [4, 5, 6]]; int[,] rectangular new int[2, 3] { { 1, 2, 3 }, { 4, 5, 6 } }; await client.InsertBinaryAsync(matrices, [id, data], [[1UL, jagged], [2UL, rectangular]]); // Read: GetValue gives you jagged... var asJagged (int[][])reader.GetValue(1); // ...but if you know its rectangular, ask for that shape directly var asRect reader.GetFieldValueint[,](1); // throws on ragged data写入链路中的 ValueTuple在二进制插入、HTTP 参数及类型推断中现在可以直接使用 C# 元组字面量await client.InsertBinaryAsync(t, [id, pair], [[1UL, (42, hello)]]); // - Tuple(Int32, String)针对元素超过 7 个的元组客户端也能从编译器生成的TRest嵌套结构中将其正确展平。服务端标识符参数现在可以将数据库名、表名或列名作为参数绑定无需手动拼接 SQL 字符串var p new ClickHouseParameterCollection(); p.AddParameter(tbl, my-tablewithbackticks); await client.ExecuteReaderAsync(SELECT * FROM {tbl:Identifier};, p);参数值会原样发送由服务端负责标识符的引号包裹与转义。因此包含特殊字符含反引号的名称均可正常传递无需在客户端处理转义逻辑。此前该操作会抛出Identifier类型未知的异常。正确性我们在本次迭代中投入了大量精力来提升正确性并修复已知缺陷。破坏性变更DateTime 时区处理本版本中最关键的破坏性变更涉及DateTime处理var p new ClickHouseParameterCollection(); p.AddParameter(ts, DateTime.UtcNow); await client.ExecuteNonQueryAsync(INSERT INTO events VALUES (ts);, p);• 之前 驱动仅发送基础的 {ts:DateTime} 提示。服务端根据 session_timezone 解析传输的挂钟时间wall-clock并依据服务端时区偏移量进行平移。在 UTC 服务器上一切正常但在 Europe/Amsterdam 等时区夏令时会导致两小时的偏差。• 之后 DateTime { Kind: Utc or Local } 和 DateTimeOffset 会被推断为 DateTime(UTC) 发送。无论服务端处于何种时区都能确保绝对时间点instant的一致性。• 显式类型提示不受影响若参数类型为 {ts:DateTime} 时区语义仍完全由调用方控制。客户端中还包含许多细节优化• Fixed/UTC±HH:MM:SS 时区 ClickHouse 的合成时区名称不在 IANA TZDB 中此前驱动会将其误认为 UTC。现在已能正确解析为固定偏移量时区。• 复合类型序列化 通过 HTTP 传输时 Array 、 Tuple 、 Map 、 Variant 内的日期时间类型现在会正确添加引号。• Variant 类型的 NULL 值 修复了读取 NULL 时抛出 IndexOutOfRangeException 以及写入 NULL 时未更少的网络往返更低的 GC 压力这两项改动侧重于性能优化旨在减少资源开销。Insert 体验优化跳过表结构探测默认情况下每次调用InsertBinaryAsync都会执行一次SELECT ... WHERE 10以探测表结构。这会产生额外的网络开销。现在可以通过以下两种方式规避// Know the schema at compile time? Declare it and skip the probe entirely. var options new InsertOptions { ColumnTypes new Dictionarystring, string { [Id] UInt64, [SensorName] LowCardinality(String), [Value] Float64, }, }; // Or probe once and reuse it for the lifetime of the client. var cached new InsertOptions { UseSchemaCache true };ColumnTypes的优先级高于UseSchemaCache且需要显式列出字段。UseSchemaCache会在客户端生命周期内按(数据库, 表)缓存结构因此如果执行了破坏性的ALTER TABLE需留意缓存失效问题。此外如果 POCO 中所有映射属性都标记了[ClickHouseColumn(Type ...)]驱动会自动跳过探测。ReadBufferSize 默认值从 512 KiB 降至 8 KiB此前响应读取缓冲区固定为 512 KiB。由于超过了 85,000 字节的大对象堆LOH阈值每次查询都会在 LOH 上分配内存LOH 默认不进行碎片整理易导致内存碎片。这带来了显著的 GC 压力。在 1000 次小型 SELECT 查询的基准测试中单次查询的内存分配减少了 80% 以上消除了 Gen 2 回收GC 总暂停时间缩短了 90% 以上。1.3 版本允许通过ClickHouseClientSettings.ReadBufferSize或连接字符串自定义缓冲区大小并将默认值降至 8 KiB。如需流式处理海量响应并减少缓冲区重填次数可手动调高此值。Entity Framework Core作为 .NET 社区呼声最高的集成EF Core 支持现已正式发布ClickHouse.EntityFrameworkCore支持查询、插入、表引擎配置及迁移并能将GROUP BY聚合、字符串方法、数学函数及 JSON 列转换为原生 ClickHouse SQL。DDL配置方式与其他 EF Core 提供程序类似public class AnalyticsContext : DbContext { public DbSetPageView PageViews { get; set; } protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) optionsBuilder.UseClickHouse(Hostlocalhost;Port8123;Databaseanalytics); }modelBuilder.EntitySensorReading(b { b.HasKey(e e.Id); b.Property(e e.Temperature).HasCodec(Delta, ZSTD); b.Property(e e.Location).HasColumnComment(Installation site); b.HasIndex(e e.Timestamp) .HasSkippingIndexType(minmax) .HasGranularity(4); b.ToTable(sensor_readings, t t .HasReplacingMergeTreeEngine(Version) .WithOrderBy(Id, Timestamp) .WithPartitionBy(toYYYYMM(Timestamp)) .WithPrimaryKey(Id) .WithTtl(Timestamp INTERVAL 1 YEAR) .WithSetting(index_granularity, 4096)); });查询构建随后即可使用 LINQ所有内容都会如预期般转换为 ClickHouse 语法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();批量插入此外你无需为了性能而放弃 EF该集成提供了高性能的.BulkInsertAsync()方法long rowsInserted await ctx.BulkInsertAsync(events); // tune the batch size at configuration time optionsBuilder.UseClickHouse(Hostlocalhost, o o.MaxBatchSize(5000));该集成还提供了表引擎 Fluent API支持多种表引擎、索引以及列级 DDL。日益完善的生态系统除 EF Core 外我们还推出了另外三个官方集成• Serilog: 通过 WriteTo.ClickHouse() 提供流式列配置和集群支持。Serilog 用户只需一行代码即可接入。详见 使用 Serilog 和 ClickHouse 在 .NET 中实现结构化日志 。• Aspire: Aspire.Hosting.ClickHouse 为应用模型添加了 ClickHouse 容器资源 Aspire.ClickHouse.Driver 在 DI 中注册了 ClickHouseDataSource 并集成健康检查、OpenTelemetry 追踪及配置绑定。详见 使用 ClickHouse 和 Aspire 构建 .NET API 网关 。• Semantic Kernel: 针对 Microsoft.Extensions.VectorData 的向量存储连接器。通过标准 SK 接口将 ClickHouse 作为向量数据库支持 CRUD、过滤查询及向量相似度计算。示例项目展示了基于 IMDb 数据集的语义搜索。展望未来1.4提升速度下一个版本1.4将聚焦性能通过减少内存分配来提升速度。预告特性包括• 大幅减少内存分配 移除部分缓冲区并引入池化机制显著降低开销。• 可插拔压缩 提供 IClickHouseCompressor 接口内置 GZip、Brotli、LZ4 和 Zstd 支持。• 免装箱的 POCO 读写 驱动将直接通过泛型接口操作跳过 object 转换节省大量分配开销。• ……以及更多特性1.5: Native/TCP 客户端我们目前正全力开发基于 TCP 协议和 Native列式格式的新客户端旨在实现更极致的性能。TCP 协议的优势包括保持列式结构。数据以“块”为单位传输采用与数据库存储一致的列式格式。这消除了服务端的 RowBinary 序列化开销。读取百万行Int64时不再需要百万次解码而是转化为高效的单次内存复制。服务端状态实时反馈。在查询执行期间Native 协议能在查询执行期间穿插返回进度更新、性能分析事件及服务端日志包括已读行数、字节数及执行进度预估。连接具有长生命周期且带有状态因此驱动无需再通过 session id 参数去模拟会话、临时表以及单连接级别的配置。链接• 安装 dotnet add package ClickHouse.Driver• 文档 https://clickhouse.com/docs/integrations/csharp• 示例 https://github.com/ClickHouse/clickhouse-cs/tree/main/examples• 如有任何反馈请在 GitHub 上联系我们https://github.com/ClickHouse/clickhouse-cs或或加入 社区 Slackhttps://clickhousedb.slack.com/join/shared_invite/zt-44wvsqbjb-53ggHzNoaCyG5k3dFDyOQA#/shared-invite/email 。关于我们ClickHouseclickhouse.com) 是面向 AI 时代打造的高性能实时分析数据库能够以极致性能处理海量数据分析任务。凭借高并发、低延迟和云原生架构ClickHouse 广泛应用于可观测性、数据仓库、实时分析及 AI 数据基础设施等场景。我们致力于帮助企业在公有云平台上构建安全、弹性且高性价比的实时分析与 AI 数据平台加速释放数据价值推动智能化创新与数字化转型。目前Trip.com、DiDi、Meta、Sony、Netflix、Deutsche Bank、Sierra、Cloudflare 等全球领先企业均在使用 ClickHouse 支撑其关键业务和数据分析平台。
本文字数12722估计阅读时间32分钟作者Alex Soffronow Pagonidis编者按本文译自 ClickHouse 原博客链接点文末-查看原文。 原文围绕「相关技术主题」展开。 文章梳理了驱动在插入、读取和参数路径上的实际变化POCO 工作流是其中最值得关注的体验升级。对仍停留在 1.0 的用户来说这是一份清晰的迁移参考。今年 2 月我们发布了 .NET 驱动的首个稳定版本。该版本重点增强了类型支持、打包方式、配置及可观测性并引入了一套独立于旧版 ADO.NET API 的全新主 API。此后我们陆续发布了三个次版本在优化用户体验的同时不断增强客户端的扩展性与可配置性并进一步丰富了支持的数据类型。此外我们还开发了多项 .NET 生态集成。这些进展离不开社区的贡献感谢在此期间提交 Issue、复现 Bug 或提交 PR 的每一位开发者特别感谢 Daniel Bunting、Vyacheslav Brevnov、Minh Vu、Ozan Hanedan 以及 Musa Musaev。如果你对该驱动的印象还停留在 1.0 版本那么现在的写入、读取及参数处理流程均已显著进化。具体变化如下。基于 POCO 的类型安全工作流这是开发体验上最显著的一项改进。在 1.0 版本中常规操作依赖object[]。现在无论是读取还是写入都可以直接使用自定义类之前 (1.0)手动转换的 object[]using var client new ClickHouseClient(Hostlocalhost); // You own the column list, the ordering, and the boxing. await client.InsertBinaryAsync( sensors, new[] { Id, SensorName, Value, RecordedAt }, readings.Select(r new object[] { r.Id, r.SensorName, r.Value, r.RecordedAt }));以前每次写入都要重复声明表结构。一旦string[]中的列顺序写错就会引发运行时序列化错误甚至导致数据被悄无声息地错位写入。现在 (1.3)一次注册直接读写自定义类型public class SensorReading { public ulong Id { get; set; } public string SensorName { get; set; } public double Value { get; set; } public DateTime RecordedAt { get; set; } } using var client new ClickHouseClient(Hostlocalhost); client.RegisterPocoTypeSensorReading(); // sets up insert read, validates both up front // Write long rows await client.InsertBinaryAsync(sensors, readings); // IEnumerableSensorReading // Read await foreach (var r in client.QueryAsyncSensorReading( SELECT * FROM sensors WHERE Value 20;)) { Console.WriteLine(${r.SensorName}: {r.Value:F2}); }类型注册在初始化阶段完成它会校验类结构并尽早拦截映射问题。由于 Getter 和 Setter 经过预编译查询时几乎没有额外开销。QueryAsyncT返回IAsyncEnumerableT支持数据行的延迟实例化。当枚举结束、报错或中途break时读取器会自动释放。以下是几条匹配规则• 列匹配区分大小写 StringComparer.Ordinal 。• 若结果集中的列没有对应的类属性该列将被忽略。• 若类中的属性没有对应的结果列该属性将保持默认值。• 类型需要一个公共无参构造函数以及至少一个带公共非 init setter 的公共属性。支持 required 属性。映射属性你还可以使用特性来控制每个属性的列和类型映射public class AuditEvent { [ClickHouseColumn(Name event_id)] public ulong Id { get; set; } [ClickHouseColumn(Name event_type, Type LowCardinality(String))] public required string Type { get; set; } [ClickHouseNotMapped] public string InternalCorrelationTag { get; set; } }驱动程序不会进行任何隐式转换。如果类型不匹配会抛出InvalidOperationException并详细说明 POCO 类型、属性、列名以及实际返回的 CLR 类型方便快速定位。为了辅助调试映射器还提供了详细日志。只要配置了LoggerFactory注册时就会输出Debug级别的日志类别为ClickHouse.Driver.Client列出属性与列的映射关系、被跳过的属性及其原因。查看日志通常比查阅文档规则更高效。将 POCO 存入 JSON 列这一特性同样适用于 ClickHouse 的JSON类型。配合RegisterJsonSerializationTypeT()以及[ClickHouseJsonPath(...)]/[ClickHouseJsonIgnore]你可以直接将 POCO 写入 JSON 列并保持类型精度需将 JsonWriteMode 设为 Binarypublic class SensorAttributes { [ClickHouseJsonPath(device.id)] public required string DeviceId { get; set; } public decimal Temperature { get; set; } [ClickHouseJsonIgnore] public string LocalDebugTag { get; set; } } using var client new ClickHouseClient(Hostlocalhost;JsonWriteModeBinary); client.RegisterJsonSerializationTypeSensorAttributes(); // attributes JSON(device.id String, Temperature Decimal64(4)) await client.InsertBinaryAsync(readings, [id, attributes], [[1UL, new SensorAttributes { DeviceId sensor-7, Temperature 21.4375m }]]);写入后的数据行为{Temperature:21.4375,device:{id:sensor-7}}。端到端自定义流水线第二个重点是控制权。虽然驱动程序提供了合理的默认值但无法覆盖所有场景。为了让开发者更灵活地控制客户端行为我们新增了三个扩展点分别负责类型解析、参数序列化以及读取时的值转换。这些扩展点均为可选不使用时不会产生额外开销。接口阶段引入版本IParameterTypeResolverCLR 类型 → ClickHouse 类型1.2IParameterFormatter值 → 传输格式1.3IReadValueConverter传输值 → 返回时的 CLR 值1.3这三个接口都可以在ClickHouseClientSettings全局客户端级别或QueryOptions单次查询级别中进行配置。1. IParameterTypeResolver控制类型推断ClickHouse 要求发往服务端的参数带有类型声明例如{name:Type}。不过驱动也支持无类型的 ADO.NET 风格参数如WHERE id id这也是 Dapper 等 ORM 常用的形式。此时驱动必须根据 CLR 值推断 ClickHouse 类型。内置的推断策略倾向于保守decimal映射为Decimal128(scale)DateTime映射为DateTime(UTC)以最大限度减少信息丢失。但如果你的表结构统一使用Decimal64(4)和DateTime64(3)这种保守策略反而会报错迫使你在代码中为每个参数手动添加注解。通过IParameterTypeResolver你可以全局定义映射约定。针对常见场景驱动提供了一个内置的字典实现var settings new ClickHouseClientSettings(Hostlocalhost) { ParameterTypeResolver new DictionaryParameterTypeResolver(new DictionaryType, string { [typeof(decimal)] Decimal64(4), [typeof(DateTime)] DateTime64(3), }), };如果逻辑需要根据具体数值或参数名进行判断可以直接实现该接口。例如下面的代码会根据传入的具体值选择能容纳它的最窄 decimal 类型private class SmartDecimalResolver : IParameterTypeResolver { public string ResolveType(Type clrType, object value, string parameterName) { if (clrType ! typeof(decimal)) return null; // let everything else use default inference var scale (decimal.GetBits((decimal)value)[3] 16) 0x7F; return scale 4 ? $Decimal64({scale}) : $Decimal128({scale}); } }如果返回null驱动会退回到默认推断逻辑因此解析器只需处理特定情况即可。2. IParameterFormatter控制传输格式仅解析出类型有时还不够因为即使类型正确格式化输出rendering也可能不符合预期。HTTP 参数以文本形式发送驱动需要决定如何序列化每个值。这通常没有争议但也有例外例如DateTime列会接收带有亚秒精度的值并直接截断你可能希望在本地显式处理这种截断而不是交给服务端处理。var settings new ClickHouseClientSettings(Hostlocalhost) { ParameterFormatter new DictionaryParameterFormatter(new DictionaryType, Funcobject, string { // e.g. clamp to whole seconds regardless of the columns declared precision [typeof(DateTime)] v ((DateTime)v).ToString(yyyy-MM-dd HH:mm:ss, CultureInfo.InvariantCulture), }), };值得注意的两点• 无论是顶层值还是复合类型 Array 、 Tuple 、 Map 、 Nested 内部的元素都会调用该格式化器。• 透明包装器 Nullable 、 LowCardinality 、 Variant 会被预先解包因此格式化器只需处理底层具体类型。此外格式化器不会处理 null 或 DBNull 它们会被统一序列化为 ClickHouse 的空值占位符。3. IReadValueConverter在返回数据时进行标准化第三个接口用于处理数据返回。假设查询的DateTime列未指定时区读取到的值Kind属性通常为Unspecified。如果应用约定“所有时间戳均为 UTC”你可以在数据离开驱动前完成转换避免在业务代码中到处调用DateTime.SpecifyKindvar settings new ClickHouseClientSettings(Hostlocalhost) { ReadValueConverter new DictionaryReadValueConverter() .ForDateTime(dt DateTime.SpecifyKind(dt, DateTimeKind.Utc)) .Forstring(s s.Trim()), };该转换器会拦截GetValue()和GetFieldValueT()并在 POCO 实例化时生效因此QueryAsyncT()也会得到转换后的值。注意DictionaryReadValueConverter仅按CLR类型匹配而DateTime和DateTime(UTC)在 C# 中都表现为System.DateTime因此上述代码也会影响已带时区的列。如果需要区分请实现该接口并根据 ClickHouse 返回的类型名称进行逻辑分支此时获取的数据与服务器原始报告完全一致private class UtcOnlyForNoTzDateTimeConverter : IReadValueConverter { public object ConvertValue(object value, string columnName, string clickHouseType) value is DateTime dt clickHouseType DateTime ? DateTime.SpecifyKind(dt, DateTimeKind.Utc) : value; public T ConvertValueT(T value, string columnName, string clickHouseType) typeof(T) typeof(DateTime) value is DateTime dt clickHouseType DateTime ? (T)(object)DateTime.SpecifyKind(dt, DateTimeKind.Utc) : value; }该接口有两个限制• 不得改变值的运行时类型。 列元数据 GetFieldType 等不会根据转换器的输出重新推导。它并非数据映射层。• 不会递归处理复合类型。 它针对每行每列调用一次传入完整的已反序列化单元格数据例如对于 Array(Int32) 列你获取到的是完整的 int[] 。提供泛型重载是为了保证热路径性能通过 typeof(T) 检查配合 Unsafe.As 即可在不装箱的情况下直接转换值类型。更细粒度的配置项秉承同样的理念我们还优化了一些配置细节• 单次查询设置 Accept-Encoding QueryOptions.AcceptEncoding 对应 ClickHouseCommand.AcceptEncoding 可覆盖单个请求默认的 gzip, deflate 编码。此操作会强制设置 enable_http_compression1 以确保服务端生效。 请注意如果使用 BCL 无法解码的压缩格式如 zstd、lz4必须在 HttpClient 中设置 AutomaticDecompression None 并通过 ExecuteRawResultAsync 读取响应体。具体编码可通过 ClickHouseRawResult.ContentEncoding 获取。• GetFieldValueT(string name) 支持按列名获取数据作为按索引获取的补充。• ApplicationInfo ClickHouseClientSettings 新增了自定义标签字典 IReadOnlyDictionarystring, string 如 app 、 ver 、 env 等。这些标签会以注释形式附加在 HTTP User-Agent 标头中例如 (app:MyApp; ver:2.3.1; env:prod) 。这在通过数据库查询日志追溯来源时非常有用。更丰富的类型支持我们持续优化了 CLR 与 ClickHouse 之间的类型映射新增了对多维数组、ValueTuples 以及 Identifier 参数的支持。嵌套与多维数组感谢 DanielBunting 的贡献现在可以将Array(Array(T))及更深层嵌套作为多维数组读写。C# 支持两种 N 维数组交错数组int[][]数组的数组行长可变和矩形数组int[,]连续内存行长固定。ClickHouse 的Array(Array(T))在结构上对应交错数组。但在处理矩形数据时强制使用交错数组会增加额外的对象分配。现在写入操作已同时支持交错数组T[][]、ListListT和矩形数组T[,]、T[,,]等。读取时默认仍为交错格式但GetFieldValueT[,]可以直接实例化为矩形数组并校验形状。// Write: jagged or rectangular, your choice int[][] jagged [[1, 2], [3], [4, 5, 6]]; int[,] rectangular new int[2, 3] { { 1, 2, 3 }, { 4, 5, 6 } }; await client.InsertBinaryAsync(matrices, [id, data], [[1UL, jagged], [2UL, rectangular]]); // Read: GetValue gives you jagged... var asJagged (int[][])reader.GetValue(1); // ...but if you know its rectangular, ask for that shape directly var asRect reader.GetFieldValueint[,](1); // throws on ragged data写入链路中的 ValueTuple在二进制插入、HTTP 参数及类型推断中现在可以直接使用 C# 元组字面量await client.InsertBinaryAsync(t, [id, pair], [[1UL, (42, hello)]]); // - Tuple(Int32, String)针对元素超过 7 个的元组客户端也能从编译器生成的TRest嵌套结构中将其正确展平。服务端标识符参数现在可以将数据库名、表名或列名作为参数绑定无需手动拼接 SQL 字符串var p new ClickHouseParameterCollection(); p.AddParameter(tbl, my-tablewithbackticks); await client.ExecuteReaderAsync(SELECT * FROM {tbl:Identifier};, p);参数值会原样发送由服务端负责标识符的引号包裹与转义。因此包含特殊字符含反引号的名称均可正常传递无需在客户端处理转义逻辑。此前该操作会抛出Identifier类型未知的异常。正确性我们在本次迭代中投入了大量精力来提升正确性并修复已知缺陷。破坏性变更DateTime 时区处理本版本中最关键的破坏性变更涉及DateTime处理var p new ClickHouseParameterCollection(); p.AddParameter(ts, DateTime.UtcNow); await client.ExecuteNonQueryAsync(INSERT INTO events VALUES (ts);, p);• 之前 驱动仅发送基础的 {ts:DateTime} 提示。服务端根据 session_timezone 解析传输的挂钟时间wall-clock并依据服务端时区偏移量进行平移。在 UTC 服务器上一切正常但在 Europe/Amsterdam 等时区夏令时会导致两小时的偏差。• 之后 DateTime { Kind: Utc or Local } 和 DateTimeOffset 会被推断为 DateTime(UTC) 发送。无论服务端处于何种时区都能确保绝对时间点instant的一致性。• 显式类型提示不受影响若参数类型为 {ts:DateTime} 时区语义仍完全由调用方控制。客户端中还包含许多细节优化• Fixed/UTC±HH:MM:SS 时区 ClickHouse 的合成时区名称不在 IANA TZDB 中此前驱动会将其误认为 UTC。现在已能正确解析为固定偏移量时区。• 复合类型序列化 通过 HTTP 传输时 Array 、 Tuple 、 Map 、 Variant 内的日期时间类型现在会正确添加引号。• Variant 类型的 NULL 值 修复了读取 NULL 时抛出 IndexOutOfRangeException 以及写入 NULL 时未更少的网络往返更低的 GC 压力这两项改动侧重于性能优化旨在减少资源开销。Insert 体验优化跳过表结构探测默认情况下每次调用InsertBinaryAsync都会执行一次SELECT ... WHERE 10以探测表结构。这会产生额外的网络开销。现在可以通过以下两种方式规避// Know the schema at compile time? Declare it and skip the probe entirely. var options new InsertOptions { ColumnTypes new Dictionarystring, string { [Id] UInt64, [SensorName] LowCardinality(String), [Value] Float64, }, }; // Or probe once and reuse it for the lifetime of the client. var cached new InsertOptions { UseSchemaCache true };ColumnTypes的优先级高于UseSchemaCache且需要显式列出字段。UseSchemaCache会在客户端生命周期内按(数据库, 表)缓存结构因此如果执行了破坏性的ALTER TABLE需留意缓存失效问题。此外如果 POCO 中所有映射属性都标记了[ClickHouseColumn(Type ...)]驱动会自动跳过探测。ReadBufferSize 默认值从 512 KiB 降至 8 KiB此前响应读取缓冲区固定为 512 KiB。由于超过了 85,000 字节的大对象堆LOH阈值每次查询都会在 LOH 上分配内存LOH 默认不进行碎片整理易导致内存碎片。这带来了显著的 GC 压力。在 1000 次小型 SELECT 查询的基准测试中单次查询的内存分配减少了 80% 以上消除了 Gen 2 回收GC 总暂停时间缩短了 90% 以上。1.3 版本允许通过ClickHouseClientSettings.ReadBufferSize或连接字符串自定义缓冲区大小并将默认值降至 8 KiB。如需流式处理海量响应并减少缓冲区重填次数可手动调高此值。Entity Framework Core作为 .NET 社区呼声最高的集成EF Core 支持现已正式发布ClickHouse.EntityFrameworkCore支持查询、插入、表引擎配置及迁移并能将GROUP BY聚合、字符串方法、数学函数及 JSON 列转换为原生 ClickHouse SQL。DDL配置方式与其他 EF Core 提供程序类似public class AnalyticsContext : DbContext { public DbSetPageView PageViews { get; set; } protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) optionsBuilder.UseClickHouse(Hostlocalhost;Port8123;Databaseanalytics); }modelBuilder.EntitySensorReading(b { b.HasKey(e e.Id); b.Property(e e.Temperature).HasCodec(Delta, ZSTD); b.Property(e e.Location).HasColumnComment(Installation site); b.HasIndex(e e.Timestamp) .HasSkippingIndexType(minmax) .HasGranularity(4); b.ToTable(sensor_readings, t t .HasReplacingMergeTreeEngine(Version) .WithOrderBy(Id, Timestamp) .WithPartitionBy(toYYYYMM(Timestamp)) .WithPrimaryKey(Id) .WithTtl(Timestamp INTERVAL 1 YEAR) .WithSetting(index_granularity, 4096)); });查询构建随后即可使用 LINQ所有内容都会如预期般转换为 ClickHouse 语法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();批量插入此外你无需为了性能而放弃 EF该集成提供了高性能的.BulkInsertAsync()方法long rowsInserted await ctx.BulkInsertAsync(events); // tune the batch size at configuration time optionsBuilder.UseClickHouse(Hostlocalhost, o o.MaxBatchSize(5000));该集成还提供了表引擎 Fluent API支持多种表引擎、索引以及列级 DDL。日益完善的生态系统除 EF Core 外我们还推出了另外三个官方集成• Serilog: 通过 WriteTo.ClickHouse() 提供流式列配置和集群支持。Serilog 用户只需一行代码即可接入。详见 使用 Serilog 和 ClickHouse 在 .NET 中实现结构化日志 。• Aspire: Aspire.Hosting.ClickHouse 为应用模型添加了 ClickHouse 容器资源 Aspire.ClickHouse.Driver 在 DI 中注册了 ClickHouseDataSource 并集成健康检查、OpenTelemetry 追踪及配置绑定。详见 使用 ClickHouse 和 Aspire 构建 .NET API 网关 。• Semantic Kernel: 针对 Microsoft.Extensions.VectorData 的向量存储连接器。通过标准 SK 接口将 ClickHouse 作为向量数据库支持 CRUD、过滤查询及向量相似度计算。示例项目展示了基于 IMDb 数据集的语义搜索。展望未来1.4提升速度下一个版本1.4将聚焦性能通过减少内存分配来提升速度。预告特性包括• 大幅减少内存分配 移除部分缓冲区并引入池化机制显著降低开销。• 可插拔压缩 提供 IClickHouseCompressor 接口内置 GZip、Brotli、LZ4 和 Zstd 支持。• 免装箱的 POCO 读写 驱动将直接通过泛型接口操作跳过 object 转换节省大量分配开销。• ……以及更多特性1.5: Native/TCP 客户端我们目前正全力开发基于 TCP 协议和 Native列式格式的新客户端旨在实现更极致的性能。TCP 协议的优势包括保持列式结构。数据以“块”为单位传输采用与数据库存储一致的列式格式。这消除了服务端的 RowBinary 序列化开销。读取百万行Int64时不再需要百万次解码而是转化为高效的单次内存复制。服务端状态实时反馈。在查询执行期间Native 协议能在查询执行期间穿插返回进度更新、性能分析事件及服务端日志包括已读行数、字节数及执行进度预估。连接具有长生命周期且带有状态因此驱动无需再通过 session id 参数去模拟会话、临时表以及单连接级别的配置。链接• 安装 dotnet add package ClickHouse.Driver• 文档 https://clickhouse.com/docs/integrations/csharp• 示例 https://github.com/ClickHouse/clickhouse-cs/tree/main/examples• 如有任何反馈请在 GitHub 上联系我们https://github.com/ClickHouse/clickhouse-cs或或加入 社区 Slackhttps://clickhousedb.slack.com/join/shared_invite/zt-44wvsqbjb-53ggHzNoaCyG5k3dFDyOQA#/shared-invite/email 。关于我们ClickHouseclickhouse.com) 是面向 AI 时代打造的高性能实时分析数据库能够以极致性能处理海量数据分析任务。凭借高并发、低延迟和云原生架构ClickHouse 广泛应用于可观测性、数据仓库、实时分析及 AI 数据基础设施等场景。我们致力于帮助企业在公有云平台上构建安全、弹性且高性价比的实时分析与 AI 数据平台加速释放数据价值推动智能化创新与数字化转型。目前Trip.com、DiDi、Meta、Sony、Netflix、Deutsche Bank、Sierra、Cloudflare 等全球领先企业均在使用 ClickHouse 支撑其关键业务和数据分析平台。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
