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'。
