跳转至

JSON Find 条件搜索与数组元素检索节点

基于自定义搜索匹配准则在 JSON 数组中快速查找和筛选项目。

节点核心功能 (Description)

JSON Find 节点专用于在复杂 JSON 数组或列表集合中检索符合特定条件的数据对象。它支持多种匹配模式（精确匹配、包含匹配、前缀匹配）、大小写敏感控制，并可自由选择返回第一个匹配项或所有满足条件的集合列表。对于在多层数据结构中执行过滤、定位与状态检查具有极高实用价值。

配置与参数规范 (Parameters)

输入插槽 (Input Parameters)

参数名称 (Parameter) 数据类型 (Type) 语义说明 (Description) 默认值 (Default)
json json, str, dict 待检索的目标 JSON 数据（应为数组，或包含数组的对象）。 []
search_field str 目标搜索字段的点号访问路径（例如 'attributes.content'）。 ""
search_value str 待匹配的目标特征值。 ""
search_mode str 匹配比较模式：'exact'（精确）、'contains'（包含）或 'starts_with'（前缀）。 "exact"
return_mode str 返回结果形态：'first'（仅返回首个匹配项）或 'all'（返回所有匹配项列表）。 "first"
case_sensitive bool 是否对文本字符进行严格的大小写匹配区分。 true

输出引脚 (Output Parameters)

输出名称 (Parameter) 数据类型 (Type) 语义说明 (Description)
found_item json 检索到的数据项（在 return_mode='first' 时为单对象，在 'all' 时为数组列表）。
found_count int 实际匹配成功的元素总个数。
found_index int 首个匹配元素在源数组中的原始索引号（若未找到则返回 -1）。

核心特性解析 (Features)

  • 多样化搜索模式：灵活切换精确相等、模糊子串包含或固定词首前缀匹配；
  • 大小写自由控制：一键开启或关闭大小写敏感性；
  • 智能数组自动探测 (Array Auto-Detection)：若输入为根字典，节点能自动深度探测并展开常见的数组字段（如 data、items、results、list 等）；
  • 深层嵌套路径穿透：通过点号语法穿透访问深层复杂对象内部的特定字段；
  • 双向返回模式：既可用于查找单一定位项，也可用于实现批量数据列表过滤。

匹配模式详解 (Search Modes)

精确匹配 (exact)

字段值必须与目标搜索值 100% 完全相同：

# 搜索目标: "Design"
# 成功匹配: "Design"
# 排除项: "Design Task", "design", "My Design"

包含匹配 (contains)

只要字段值中包含指定子串即可命中：

# 搜索目标: "Design"
# 成功匹配: "Design", "Design Task", "My Design Work"
# 排除项: "design" (若 case_sensitive=true)

前缀匹配 (starts_with)

字段值以指定子串开头：

# 搜索目标: "Design"
# 成功匹配: "Design", "Design Task", "Designer"
# 排除项: "My Design", "design"

使用代码示例 (Examples)

按属性精确查找首个任务

# 输入 JSON: [
#   {"attributes": {"content": "Design", "status": "wtg"}},
#   {"attributes": {"content": "Model", "status": "wtg"}},
#   {"attributes": {"content": "Design Review", "status": "ip"}}
# ]
# search_field: "attributes.content"
# search_value: "Design"
# search_mode: "exact"
# return_mode: "first"
# 输出 found_item: {"attributes": {"content": "Design", "status": "wtg"}}
# 输出 found_count: 1
# 输出 found_index: 0

状态字段批量过滤 (返回全部)

# search_field: "attributes.status"
# search_value: "wtg"
# return_mode: "all"
# 输出 found_item: [
#   {"attributes": {"content": "Design", "status": "wtg"}},
#   {"attributes": {"content": "Model", "status": "wtg"}}
# ]
# 输出 found_count: 2

忽略大小写模糊搜索

# 输入 JSON: [{"name": "Design Task"}, {"name": "design review"}, {"name": "DESIGN WORK"}]
# search_field: "name"
# search_value: "design"
# search_mode: "contains"
# case_sensitive: false
# return_mode: "all"
# 输出: 命中全部 3 个项目

典型适用场景 (Use Cases)

  • 任务管理系统流转：按处理状态、指派人或优先级从待办任务数组中筛选出特定项目；
  • 大型数据集过滤：根据用户选择的筛选标签就地过滤列表；
  • API 列表响应检索：从多页返回的数据集中精准提取特定 ID 的记录；
  • 配置项查找：从全局环境变量或规则列表中检索目标特定参数。