SonnetDB：批量写入的大小、背压与刷新策略

本文介绍 SonnetDB 的批量写入与刷新策略，重点是分别控制请求大小、等待队列和确认语义，而不是给出未经测量的吞吐承诺。

SQL 批量与类型化写入是不同入口

SQL 多行 VALUES 可以在一个 INSERT 中表达多行数据。类型化时序客户端则提供 SndbTimeSeriesClient、CreateWriter 与 WriteAsync 等入口。不能把某个客户端的批次上限直接套用成所有 SQL 或远程入口的统一限制。

当前 SndbTimeSeriesWriteOptions 中，BatchSize 默认 512，控制一次传输的点数；MaxBatchPoints 默认 8192，控制一次 WriteBatchAsync 可接收的点数，当前校验范围为 1...65536。输入更大时应由调用方有界拆分。

csharp 复制代码

using SonnetDB.Data.TimeSeries;

var options = new SndbTimeSeriesWriteOptions
{
    BatchSize = 512,
    MaxBatchPoints = 8192,
    MaxPendingBatches = 4,
    MaxRetries = 0
};

这里展示当前默认选项，不能将它当作特定硬件上的最佳参数。实际 BatchSize 的校验范围与 MaxBatchPoints 也不同，应分别核对。

背压不是无限缓存

MaxPendingBatches 控制等待批次数，达到上限时写入方异步等待。它既不是按字节计算的完整内存预算，也不证明任意生产者输入都可以无限缓存。

调参时应同时记录批次字节数、点数、等待时间、服务端延迟及分配压力。固定行数的批次可能因字符串长度、TAG 数量或字段数不同而有很不一样的内存和传输成本。

刷新策略不能冒称事务或关闭 WAL

当前客户端选项有 None、Async、Sync 刷新模式。嵌入式批次完成后，Async 路径调用 SignalFlush，Sync 路径调用 FlushNow；None 表示不附加该批次主动刷新动作，不等于"无 WAL 模式"。

远程 Frame 与 REST 路径会传递刷新选择，其运行时及故障恢复边界仍须单独验收。批次确认、WAL 持久化、Segment 刷新和多语句事务是不同层次，不能凭一个 flush 选项就宣称所有写入原子提交。

响应丢失时保留未知

MaxRetries 默认 0。请求报错或响应丢失时，服务端可能已经接受部分或全部数据。只有明确核过业务幂等语义后，才考虑启用重试；逐项结果和整体调用异常应分别处理。

本文不保留原稿中未经当前证据支持的"每秒数十万行"、固定延迟表或 BEGIN BATCH 示例。需要性能结论时，应在指定版本、数据模型、硬件、确认策略和故障场景下单独测量。封面为写入流程示意，不代表实测性能。

本文依据 2026-10-17 当前源码复核；本轮未执行数据库、基准或生产恢复验证。

依据：TimeSeriesWriteModels.cs、SndbTimeSeriesClient.cs 与 SqlParser.cs。