用 Ingest Pipeline 为 Elasticsearch 文档添加分类标记字段

处理一批日志或任务记录数据时，我们常常需要对某些文本字段进行内容识别，并据此写入一个分类字段，供后续查询、聚合或可视化使用。
本文记录一次完整的实现过程，涵盖尝试失败的 runtime 字段、mapping 坑、pipeline 脚本处理、update_by_query 批量写入等关键细节。

✅ 背景与目标

目标是在已有字段（如 text_field）中，根据其内容添加一个新的字段（如 category_tag），其值可为 type_a、type_b、type_c 或 other。

❌ 尝试失败方案：Runtime 字段

尝试通过动态脚本字段来临时生成：

PUT your_index/_mapping
{
  "runtime": {
    "variant_mode": {
      "type": "keyword",
      "script": {
        "source": """
          if (doc['text_field'].value.contains('pattern A')) emit('type_a');
          else if (...) emit('type_b');
          else emit('default');
        """
      }
    }
  }
}

结果：
• 查询能出结果，但 速度极慢
• 无法用于 dashboard 高频聚合
• 动态字段 无法写入硬字段，每次都重新计算

结论：弃用

⚠️ 踩坑：category_tag 字段 mapping 不存在
在使用 ingest pipeline 写入字段前，请确保字段 mapping 已存在，否则查询 .keyword 会失败：

PUT your_index/_mapping
{
  "properties": {
    "variant_mode": {
      "type": "keyword"
    }
  }
}

建议预先添加 mapping，避免因动态字段导致 .keyword 查询失败或 mapping 冲突。

✅ 推荐方案：Ingest Pipeline + 批量更新
通过自定义处理流程将分类字段写入文档，适合持久保存字段且查询高效。

Ingest Pipeline 示例

PUT _ingest/pipeline/add-category-tag
{
  "description": "Add category_tag based on text_field content",
  "processors": [
    {
      "script": {
        "lang": "painless",
        "source": """
          String txt = (ctx.containsKey('text_field') && ctx.text_field instanceof String) ? ctx.text_field : "";
          if (txt.contains("pattern A")) {
            ctx.category_tag = "type_a";
          } else if (txt.contains("pattern B")) {
            ctx.category_tag = "type_b";
          } else if (txt.contains("pattern C")) {
            ctx.category_tag = "type_c";
          } else {
            ctx.category_tag = "other";
          }
        """
      }
    }
  ]
}

🛠 小批量更新触发 pipeline
考虑索引数据量较大，可使用分页式更新，避免资源阻塞：

POST your_index/_update_by_query?pipeline=add-category-tag
{
  "query": {
    "match_phrase": {
      "text_field": "pattern C"
    }
  },
  "size": 10
}

批量更新也可指定 conflicts=proceed 处理版本冲突：

POST your_index/_update_by_query?conflicts=proceed&pipeline=add-category-tag

🔍 验证字段是否写入成功

GET your_index/_search
{
  "query": {
    "term": {
      "category_tag": "type_c"
    }
  }
}

触发 pipeline 的更新命令

POST your_index/_update_by_query?pipeline=add-category-tag
{
  "query": {
    "match_all": {}
  },
  "size": 1000
}

战补充：处理共用 URL 的多文档场景

某些场景下，一批文档共用相同业务字段（如 URL），但只有部分命中分类条件。

此时建议：
• 仅更新命中的那批文档，其他文档保持无 category_tag 字段
• 避免盲目将未命中文档写入 "default"，否则会混淆含义（例如 1 个命中 type_a，999 个变成 default）

实际收获
• 查询与聚合性能显著提升
• 分类字段结构清晰可控
• 避免了 runtime 的动态计算带来的瓶颈

✅ 总结

方法	优点	缺点
Runtime 字段	实现简单，无需更改已有数据	查询性能差，不可用于聚合或排序
Pipeline 更新	支持字段持久化，适合聚合、查询和过滤	需单独触发 update_by_query
Mapping 提前定义	避免 .keyword 查询失败，保证一致性	需手动设置，不支持动态类型推断
批量更新	控制更新粒度，避免资源占用或 502 错误	若无 conflicts=proceed 可能报错

建议路径：提前定义字段 mapping + 编写 Ingest Pipeline + 小批量 update_by_query 触发处理

⸻

这次实践验证了：Runtime 字段不适合高性能查询，Pipeline 才是高效分类字段的可靠方案。

如你也在处理结构化分类字段，推荐你跳过 Runtime，直接走 Ingest Pipeline + 小批量更新路径，更稳定、更高效。

⸻

如你也在处理类似日志或文本识别任务，建议优先考虑 Ingest Pipeline 的方式，一次写入，多次复用。