NoSQL 与搜索 / 系统课时
模拟与调试处理管道
模拟与调试处理管道
本课解决处理管道上线前无法确认字段变化与失败路径的问题。你将创建一条可测试的 Ingest Pipeline,使用 _simulate 查看每个处理器的结果,并根据失败元数据定位配置错误,避免异常文档直接写入正式索引。
学习目标
- 创建包含字段清洗、类型转换和失败处理的管道
- 使用模拟接口验证成功文档与异常文档
- 根据处理器状态和失败元数据定位问题
构建可模拟的处理链路
Ingest Pipeline 会按 processors 的顺序处理文档。普通写入会直接执行管道,而 _simulate 只返回处理后的临时结果,不会把文档保存到索引,因此适合在发布前验证字段类型、条件分支和失败处理。
启用 verbose=true 后,响应会按处理器返回执行状态。某个处理器失败时,正常链路停止,随后执行管道级 on_failure。调试时应同时检查最终 _source、失败消息以及失败处理器的类型和标签。

下面的管道清理商品名称和分类,将价格转为浮点数,并写入处理时间。每个关键处理器都设置 tag,失败时可直接识别出错位置。
PUT _ingest/pipeline/product-cleanup
{
"description": "Clean product fields before indexing",
"processors": [
{
"trim": {
"field": "name",
"tag": "trim-name"
}
},
{
"lowercase": {
"field": "category",
"tag": "normalize-category"
}
},
{
"convert": {
"field": "price",
"type": "double",
"tag": "convert-price"
}
},
{
"set": {
"field": "ingested_at",
"value": "{{{_ingest.timestamp}}}",
"tag": "set-ingested-at"
}
}
],
"on_failure": [
{
"set": {
"field": "error.message",
"value": "{{{_ingest.on_failure_message}}}"
}
},
{
"set": {
"field": "error.processor_type",
"value": "{{{_ingest.on_failure_processor_type}}}"
}
},
{
"set": {
"field": "error.processor_tag",
"value": "{{{_ingest.on_failure_processor_tag}}}"
}
}
]
}预期输出
{
"acknowledged": true
}该配置创建成功后仍不会处理任何数据。只有写入请求显式指定 pipeline=product-cleanup,或索引设置了默认管道时,它才会参与正式写入。
验证成功与失败路径
一次模拟可以放入多条文档,便于比较正常值和异常值。下面第二条文档故意把 price 写成无法转换的字符串。
POST _ingest/pipeline/product-cleanup/_simulate?verbose=true
{
"docs": [
{
"_source": {
"name": " Wireless Mouse ",
"category": "ACCESSORIES",
"price": "19.90"
}
},
{
"_source": {
"name": " Mechanical Keyboard ",
"category": "ACCESSORIES",
"price": "unknown"
}
}
]
}预期结果
HTTP 200
第 1 条文档:四个处理器均为 success,name 去除首尾空格,category 变为 accessories,price 变为 19.9,并生成 ingested_at。
第 2 条文档:convert-price 失败,正常链路停止,随后生成 error.message、error.processor_type=convert 和 error.processor_tag=convert-price。响应中的时间、内部版本号等动态值可能不同,可用 <TIME>、<ID> 理解其位置。调试重点不是逐字匹配整段响应,而是确认每个处理器状态、最终字段类型和失败链路是否符合设计。
根据结果定位并上线
字段缺失时,默认会导致部分处理器失败。可选字段应明确设置 ignore_missing,必填字段则应保留失败并通过 on_failure 记录原因。不要为了让模拟通过而普遍启用 ignore_failure,否则错误数据会继续流向后续处理器。
若响应提示管道不存在,先检查管道 ID;若类型转换失败,核对源字段的真实取值;若脚本或模板取值为空,检查字段路径和 Mustache 表达式。修复后重复执行同一组模拟文档,直到成功与失败样本都得到预期结果,再用测试索引进行一次真实写入验证。
本课总结
_simulate能在不写入索引的前提下验证管道结果verbose=true、处理器tag和失败元数据可以快速定位错误步骤- 上线前必须同时覆盖正常样本、边界样本和故意失败样本
下一课预告
下一课将把关系数据库中的数据接入 Logstash,通过 JDBC 输入、字段转换和 Elasticsearch 输出完成批量导入与增量同步。