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 压力甚至
OutOfMemoryExceptionJSON 场景下，别用
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'。
