C# 文件上传到ClickHouse C#如何将CSV/JSON文件高效导入ClickHouse

clickhouse .net sdk 不支持直接文件上传，需流式读取csv/json并分批插入；避免内存溢出和性能瓶颈，须调优服务端配置。

ClickHouse 官方 .NET SDK 不支持直接文件上传

ClickHouse 没有类似 mysql 的 LOAD DATA INFILE 或 postgresql 的 copy 命令供 C# 客户端直接传文件。所谓“文件上传”，本质是：读取本地 CSV/json → 解析为行 → 构造成批量插入语句或二进制块 → 通过 http/TCP 协议发给服务端。官方 ClickHouse.Client 库只提供 SQL 查询和参数化插入，不封装文件解析逻辑。

常见错误现象：System.IO.FileNotFoundException（误以为 SDK 支持路径参数）、插入极慢（逐行 INSERT INTO ... VALUES (...)）、内存爆掉（一次性读全大文件再解析）。

• 别写 client.Execute("INSERT INTO t format CSV", FileStream) —— 这语法根本不存在
• 避免用 File.ReadAllLines() 加载 >100MB 的 CSV，会触发 GC 压力甚至 OutOfMemoryException
• JSON 场景下，别用 JObject.Parse() 处理每行 —— System.Text.Json 的 JsonDocument.ParseValue(ref Utf8JsonReader) 更轻量

用 ClickHouse.Client + StreamReader 流式导入 CSV

核心思路是分批读、分批插，绕过单次请求体积限制（默认 HTTP 请求体上限约 100MB），也避免内存堆积。关键在控制批大小（batchSize）和复用 ClickHouseConnection。

使用场景：CSV 字段数固定、无嵌套结构、编码为 UTF-8（bom 可能导致首列乱码）。

• 用 StreamReader 配合 Peek() 和 ReadLine() 流式读，不缓存整文件
• 每读 batchSize 行（建议 5000–20000），调用 connection.InsertAsync<t>()</t>，其中 T 是匹配表结构的 record 类型
• 确保 CSV 表头与 ClickHouse 表字段顺序、类型严格一致；时间字段需转成 DateTimeOffset 或字符串（如 "2024-01-01 12:00:00"）
• 连接字符串里加 compress=true 和 send_timeout=600，应对大批次网络延迟

示例片段：

var options = new ClickHouseConnectionOptions("Host=localhost;Port=8123;Database=default;compress=true;send_timeout=600"); using var conn = new ClickHouseConnection(options); await conn.OpenAsync(); using var reader = new StreamReader("data.csv"); reader.ReadLine(); // skip header var batch = new List<MyRecord>(); string? line; while ((line = await reader.ReadLineAsync()) != null) {     if (string.IsNullOrWhiteSpace(line)) continue;     var parts = line.Split(',');     batch.Add(new MyRecord { Id = int.Parse(parts[0]), Name = parts[1], Ts = DateTimeOffset.Parse(parts[2]) });     if (batch.Count >= 10000) {         await conn.InsertAsync(batch);         batch.Clear();     } } if (batch.Count > 0) await conn.InsertAsync(batch);

JSON 导入必须走 INSERT … FORMAT JSONEachRow

ClickHouse 原生支持 JSONEachRow 格式，但 C# SDK 默认不识别它 —— 你不能把 JSON 字符串当参数传给 InsertAsync。必须手动构造 HTTP 请求体，或改用 HttpClient 直连。

性能影响：相比 CSV，JSON 解析开销高 20%–40%，且字段名重复传输浪费带宽；但优势是 schema 灵活、支持嵌套对象（需用 JSON 类型字段接收）。

• 构造请求时，Content-Type 必须设为 application/x-www-form-urlencoded 或 text/plain; charset=utf-8，并在 URL 后加 ?format=JSONEachRow
• 每行一个 JSON 对象，不可换行、不可逗号分隔（不是 JSON Array），例如：{"id":1,"name":"a","ts":"2024-01-01"}
• 中文字段值必须 UTF-8 编码，且不能含 BOM；否则返回 Code: 117. DB::Exception: Unknown format JSONEachRow
• 用 HttpClient.PostAsync() 发送，禁用自动重定向（AllowAutoRedirect = false），避免 307 重定向截断 body

简短示意：

using var client = new HttpClient(); var content = new StringContent(jsonLines, Encoding.UTF8, "text/plain"); content.Headers.ContentType.CharSet = "utf-8"; var response = await client.PostAsync("http://localhost:8123/?database=default&query=INSERT%20INTO%20t%20FORMAT%20JSONEachRow", content);

大文件导入时，ClickHouse 服务端配置必须调优

即使 C# 端写得再高效，服务端默认配置会成为瓶颈：超时、内存不足、并发拒绝。这些不是代码能绕过的。

容易被忽略的点：max_insert_block_size 控制单次 INSERT 最大行数，默认 1024，远低于流式批处理的 10000；max_memory_usage 影响 INSERT 期间排序和压缩内存上限。

• 修改 /etc/clickhouse-server/config.xml 或用户配置文件：<max_insert_block_size>100000</max_insert_block_size>
• 调高 <max_memory_usage>10000000000</max_memory_usage>（10GB），尤其当启用 ReplacingMergeTree 时
• 临时禁用 check_table_dependencies 和 optimize_on_insert，减少 INSERT 时的元数据检查开销
• 如果用分布式表，确认 insert_distributed_sync = 1，否则客户端无法感知写入失败

改完记得 sudo systemctl restart clickhouse-server，且要验证：select value FROM system.settings WHERE name = 'max_insert_block_size'。