规则匹配处理器
View as Markdown

规则匹配处理器 #

需要 Rules 插件、有效 License，以及已成功编译的规则库

check_match_rules 处理器将 规则引擎接入 Ingest Pipeline，在文档写入阶段执行规则匹配并自动打标。

语法 #

{
  "check_match_rules": {
    "id": "my_ruleset"
  }
}

配置参数 #

参数是否必填描述
id必填规则库 ID（对应已编译的 repo_id）
target_field可选匹配结果写入字段，默认 tags
fields可选文档字段白名单；指定后仅这些字段按原字段名参与匹配，其余字段内容不会丢弃，而是汇总到 default_match_field
default_match_field可选当配置了 fields 时，未包含字段会汇总到该字段名参与匹配，默认 content
regex_start_at_word可选控制底层正则匹配是否从词边界起算，默认 true，通常保持默认即可
ignore_missing可选为 true 时，处理阶段发生异常会直接返回原文档并继续后续处理；默认 false，避免掩盖 License、规则库或配置问题
description可选处理器描述
if可选处理器执行条件
ignore_failure可选为 true 时，处理器失败后忽略并继续执行，默认 false
on_failure可选处理器失败时执行的处理器列表
tag可选处理器标识

工作原理 #

  1. 提取文档字段：
    • 未配置 fields：提取所有非 _ 前缀字段（含嵌套展平）
    • 配置 fields：白名单字段保留原名，其余字段值拼接到 default_match_field
  2. 执行规则匹配：传入底层规则匹配引擎
  3. 写入结果：命中后将标签数组写入 target_field

使用步骤 #

前置条件 #

在创建 Pipeline 前，请先完成以下检查：

  • 已安装并加载 rules 插件
  • 已安装有效 License，且 rule-engine 特性已启用
  • 目标规则库已导入并执行过 POST /_match_rules/{repo_id}/_compile

完整安装与 License 步骤见 规则引擎文档。

最小编译请求示例：

POST /_match_rules/{repo_id}/_compile
{}

步骤 1：如果只想先验证规则命中，可先直连规则库模拟 #

在创建 Pipeline 前，如果你只是想确认“这批文档会命中哪些规则”，可以先调用 Rules 插件自己的模拟接口：

POST /_match_rules/my_ruleset/_simulate
{
  "docs": [
    {
      "_id": "doc-1",
      "_source": {
        "title": "测试文档",
        "content": "这是需要进行规则检测的文本内容"
      }
    }
  ]
}

这个接口只返回规则命中结果，不会执行完整 ingest pipeline。

注意：

  • 它默认按“编译后的规则库 + 输入 _source”直接匹配
  • 如果你希望匹配语义尽量贴近当前处理器，也可以在请求体中显式传 fields、default_match_field、regex_start_at_word
  • 如果规则库在 _compile 时声明了 composite，这里会直接使用那套已编译结果；但 /_simulate 请求本身不支持临时传 composite
  • 如果你要验证完整 ingest 流程，而不只是规则命中，请继续使用下面的 pipeline /_simulate 做最终验证

完整用法见 规则引擎文档。

步骤 2：创建管道 #

PUT /_ingest/pipeline/rules_pipeline
{
  "description": "实时规则匹配",
  "processors": [
    {
      "check_match_rules": {
        "id": "my_ruleset",
        "target_field": "tags"
      }
    }
  ]
}

步骤 3：先用 _simulate 验证 #

POST /_ingest/pipeline/rules_pipeline/_simulate
{
  "docs": [
    {
      "_source": {
        "title": "测试文档",
        "content": "这是需要进行规则检测的文本内容"
      }
    }
  ]
}

步骤 4：查看模拟结果 #

{
  "docs": [
    {
      "doc": {
        "_source": {
          "title": "测试文档",
          "content": "这是需要进行规则检测的文本内容",
          "tags": ["敏感词规则A", "内容分类规则B"]
        }
      }
    }
  ]
}

步骤 5：写入实际数据 #

PUT /my_index/_doc/1?pipeline=rules_pipeline
{
  "title": "测试文档",
  "content": "这是需要进行规则检测的文本内容"
}

步骤 6：查看写入结果 #

{
  "_source": {
    "title": "测试文档",
    "content": "这是需要进行规则检测的文本内容",
    "tags": ["敏感词规则A", "内容分类规则B"]
  }
}

字段行为 #

默认行为 #

不配置 fields 时，处理器会提取所有非 _ 前缀字段参与匹配，嵌套对象会按路径展平。

指定字段白名单 #

配置 fields 后：

  • 白名单中的字段按原字段名参与匹配
  • 不在白名单中的字段不会被丢弃
  • 这些字段的值会被拼接到 default_match_field

示例：

{
  "check_match_rules": {
    "id": "my_ruleset",
    "fields": ["title", "content"],
    "default_match_field": "content"
  }
}

如果文档为：

{
  "title": "新品发布",
  "content": "这是正文",
  "author": "张三",
  "source": "新华网"
}

且 Pipeline 配置为：

{
  "check_match_rules": {
    "id": "my_ruleset",
    "fields": ["title", "content"],
    "default_match_field": "content"
  }
}

那么：

  • title 仍以 title 字段参与匹配
  • content 仍以 content 字段参与匹配
  • author 和 source 的值会追加进 content

注意事项 #

  • 规则库需先通过 POST /_match_rules/{repo_id}/_compile 编译
  • id 对应的是已经编译成功并同步到当前 Ingest 节点的规则库
  • 正则类型的字段值（以 (、{ 或 [ 开头）会被识别为正则模式
  • ignore_missing = true 会吞掉处理阶段异常并返回原文档，排障阶段建议保持默认值 false
  • 如果处理器创建时报 repository directory does not exist，通常表示规则库尚未编译到当前节点，或节点同步尚未完成
  • 建议将规则库维护、导入、编译流程统一在 规则引擎文档 中管理
©INFINI.LTD, All Rights Reserved.