企业官网建设流程全解析

valkey-benchmark 如何用 --dataset 加载 CSV 数据集做真实数据压测？

【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv

valkey-benchmark默认压测用的是随机生成的 key 和 value，测出来的是"随机负载"下的表现。如果你想知道真实业务数据（比如带标题、正文的文档，或者不同长度分布的字段）对服务端的影响，可以启用它的 dataset 模式：用--dataset <file>指定一个 CSV/TSV 文件，在压测命令模板里用__field:字段名__占位符引用文件中的列，压测时这些占位符会被真实数据逐条替换。本文基于仓库中valkey-benchmark的帮助输出（src/valkey-benchmark.c）、dataset 加载实现（src/valkey-benchmark-dataset.c）和集成测试（tests/integration/valkey-benchmark.tcl），给出从准备数据文件到验证写入结果的完整操作流程。

准备条件

1. 构建二进制。在仓库根目录执行make（见 README.md 的构建说明），构建产物包括valkey-benchmark和valkey-server。
2. 启动一个可用的 Valkey 实例。benchmark 默认连接127.0.0.1:6379，也可以用-h <hostname>、-p <port>指向其他实例。
3. 准备数据文件。数据集文件要求：
   • 第一行是表头（header），字段名从表头自动发现，命令里引用的字段名必须与表头完全一致；
   • 支持 CSV；文件名包含.tsv时按制表符分隔解析，其余文件名按 CSV 解析（格式判断逻辑在 datasetInit）；
   • 字段值中如果包含分隔符（如逗号），用双引号包裹即可，解析时会去掉引号并保留引号内的逗号。

仓库测试里用的数据文件长这样（来自 tests/integration/valkey-benchmark.tcl 的 CSV 字段占位符测试，测试代码示例）：

title,content,author Test Title 1,Test Content 1,Author 1 Test Title 2,Test Content 2,Author 2

包含逗号的字段要加引号：

id,title 1,"Book, Part 1"

执行压测：命令模板 +__field占位符

dataset 模式下的命令形式是标准的 benchmark 命令行：

valkey-benchmark [OPTIONS] [--] [COMMAND ARGS...]

其中[COMMAND ARGS...]就是你压测要发的命令模板。使用--dataset时有两条硬性要求：

1. 必须提供命令——只给--dataset不给命令会报错退出：Error: Dataset mode requires a command with field placeholders；
2. 命令模板里至少出现一个__field:xxx__占位符——否则报错Error: Dataset mode requires at least one field placeholder，因为数据集加载了却不会被使用。

--dataset相关的选项（来自帮助输出）：

--dataset <file> Path to CSV/TSV dataset file for field placeholder replacement. All fields auto-detected with natural content lengths. --maxdocs <num> Maximum number of documents to load from dataset file. Default: unlimited.

__field:name__的含义是"替换为数据集中指定字段/列的数据"，且依赖--dataset选项。key 部分仍可用__rand_int__生成随机 key，其随机范围由-r <keyspacelen>决定（替换为 0 到 keyspacelen-1 的 12 位数字）。

最短主路径（测试中的真实用例，向doc:<随机 key>写哈希，title/content 两个字段取自数据集）：

valkey-benchmark --dataset dataset.csv -n 4 -r 10 -- HSET doc:__rand_int__ title "__field:title__" content "__field:content__"

参数含义（依据帮助输出与测试用例）：

• --dataset dataset.csv：数据集文件路径，按 CSV 解析；
• -n 4：总请求数 4；
• -r 10：__rand_int__在 0..9 范围内取值，即最多 10 个不同 key；
• -c未指定时为默认 50 个并行连接；
• --之后是命令模板，title、content是哈希字段名，__field:title__会被替换为该行数据集记录中title列的值。

每条请求会循环遍历数据集记录（记录计数器对记录总数取模），同一请求内多个__field占位符取自同一条记录，保证行内一致性。

可选分支：限制加载量。数据文件很大时，用--maxdocs只加载前 N 条：

valkey-benchmark --dataset dataset.csv --maxdocs 2 -n 4 -r 10 -- SET item:__rand_int__ "__field:value__"

--maxdocs缺省为 unlimited。若指定的--maxdocs大于文件实际行数，会加载全部可用记录并循环使用它们，不会报错。

可选分支：TSV 文件。文件名含.tsv即按制表符分隔：

valkey-benchmark --dataset dataset.tsv -n 4 -r 10 -- HSET tsv_doc:__rand_int__ name "__field:name__" value "__field:value__" count __field:count__

可选分支：CSV 格式输出结果。加--csv让 benchmark 以 CSV 打印性能数据；同时数据集的加载诊断信息（如Loading dataset from ...、Loaded N documents...）走 stderr，不会混进 CSV 输出：

valkey-benchmark --dataset dataset.csv --csv -n 4 -r 10 -- SET item:__rand_int__ "__field:value__"

不加--csv或-q时，这些数据加载进度会直接打印到终端，便于观察大文件加载过程。

验证压测结果

测试套件中的验证方式就是"压测完去库里查值"，可以照做：

1. 查本次压测写入的 key（以doc:*前缀为例）：

valkey-cli keys "doc:*"

2. 抽查某个 key 的值，确认写入的内容确实来自数据集文件，而不是随机数据：

valkey-cli hget <上一步取到的 key> title valkey-cli hget <上一步取到的 key> content

对上面的 CSV 示例，title的值应是Test Title 1或Test Title 2，content对应Test Content 1/Test Content 2——这正是测试中断言的内容。对SET类命令则用valkey-cli get <key>，值应等于数据集中对应列的内容。

另外可以用服务端统计核对命令次数（测试里用的就是config resetstat先清零、压测后查commandstats）：

valkey-cli config resetstat # 运行上面的压测命令 valkey-cli info commandstats | grep hset

输出中cmdstat_hset的calls=应与-n指定的请求数一致（上面的例子是calls=4，测试代码示例）。

常见报错与限制

两点边界需要留意：

• -t内置测试（如-t set,get）不能替代命令模板。dataset 模式要求--后跟带字段占位符的自定义命令，--dataset与-t set组合会因缺少__field占位符而报错。
• 数据集记录是循环使用的，请求数超过记录数时同一行数据会被反复压入不同 key（或同一批 key），做容量评估时要按-r的 key 空间大小理解最终 keyspace，而不是按数据集行数。

完成一次带真实数据的压测后，如果你还想对比不同数据大小或不同命令形态下的表现，可以直接替换命令模板（SET/HSET/LPUSH等）与--maxdocs重新跑，验证方式不变。实现细节可进一步参考 src/valkey-benchmark-dataset.c 中的字段发现与逐条替换逻辑。

【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv