Appearance

JQ Transform 任务 ​

JQ Transform 是 Taskflow 中的一个强大的数据转换任务，基于 JQ 查询语言实现。它提供了灵活且高效的 JSON 数据处理能力，支持复杂的数据转换、过滤和重构操作。

核心特性 ​

  1. 数据处理

    • JSON 数据转换
    • 复杂查询支持
    • 数组操作处理

  2. 查询语言

    • 强大的 JQ 语法
    • 内置函数库
    • 链式操作支持

  3. 性能优化

    • 高效的执行引擎
    • 内存优化处理
    • 流式数据支持

任务参数 ​

参数描述必需/可选
queryExpressionJQ 查询表达式，用于转换输入数据。支持完整的 JQ 语法。必需
inputParameters输入参数映射，可在查询表达式中通过 . 访问。可选

JQ 语法基础 ​

1. 基本操作符 ​

.                   # 当前对象
.foo               # 访问字段
.foo.bar           # 嵌套访问
.[0]               # 数组索引
.[]                # 数组迭代

2. 内置函数 ​

length             # 计算长度
keys               # 获取对象键
map(expression)    # 数组映射
select(condition)  # 条件过滤
sort               # 排序

3. 数据转换 ​

{key: value}       # 构造对象
[expression]       # 构造数组
if-then-else      # 条件判断

配置示例 ​

1. 基础转换 ​

{
  "name": "transform_data",
  "taskReferenceName": "transform_ref",
  "type": "JSON_JQ_TRANSFORM",
  "inputParameters": {
    "queryExpression": "{ id: .userId, name: .userName }",
    "userId": "${workflow.input.id}",
    "userName": "${workflow.input.name}"
  }
}

2. 数组处理 ​

{
  "name": "process_array",
  "taskReferenceName": "array_transform_ref",
  "type": "JSON_JQ_TRANSFORM",
  "inputParameters": {
    "queryExpression": ".items | map({ id: .id, total: (.price * .quantity) })",
    "items": "${workflow.input.orderItems}"
  }
}

3. 复杂转换 ​

{
  "name": "complex_transform",
  "taskReferenceName": "complex_transform_ref",
  "type": "JSON_JQ_TRANSFORM",
  "inputParameters": {
    "queryExpression": "
      {
        summary: {
          total: (.items | map(.price * .quantity) | add),
          count: (.items | length),
          average: (.items | map(.price * .quantity) | add) / (.items | length)
        },
        details: (.items | map({
          id: .id,
          name: .name,
          subtotal: (.price * .quantity),
          discount: (if .quantity > 10 then (.price * .quantity * 0.1) else 0 end)
        }))
      }
    ",
    "items": "${workflow.input.items}"
  }
}

最佳实践 ​

  1. 查询优化

    • 保持表达式简洁
    • 使用适当的中间变量
    • 避免重复计算

  2. 错误处理

    • 验证输入数据
    • 处理空值和异常
    • 提供默认值

  3. 性能考虑

    • 减少数据复制
    • 优化数组操作
    • 合理使用过滤器

常见用例 ​

1. 数据清洗 ​

# 移除空字段并标准化格式
{
  name: (.name | ascii_downcase),
  email: (.email | ascii_downcase),
  age: .age
} | with_entries(select(.value != null))

2. 数据聚合 ​

# 按类别分组并计算统计
group_by(.category) | map({
  category: .[0].category,
  count: length,
  total: map(.amount) | add,
  items: map({id: .id, amount: .amount})
})

3. 数据验证 ​

# 验证必填字段和格式
if .email == null then
  error("Email is required")
elif test("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$") | not then
  error("Invalid email format")
else
  .
end

调试技巧 ​

  1. 分步调试

    # 使用 debug 函数输出中间结果
debug | .field | debug

  2. 错误定位

    # 使用 try-catch 捕获错误
try .field catch error("Invalid field access")

  3. 数据检查

    # 类型和结构验证
if type != "object" then
  error("Expected object input")
else
  .
end

性能优化 ​

  1. 减少遍历

    • 合并多次遍历
    • 使用索引访问
    • 避免重复计算

  2. 内存管理

    • 限制中间结果大小
    • 使用流式处理
    • 及时释放资源

  3. 查询优化

    • 简化表达式
    • 使用内置函数
    • 避免递归操作

使用限制 ​

  1. 数据大小

    • 输入数据限制
    • 输出数据限制
    • 内存使用限制

  2. 执行时间

    • 查询超时设置
    • 复杂度限制
    • 递归深度限制

  3. 功能限制

    • 不支持外部调用
    • 不支持状态保持
    • 不支持异步操作

错误处理 ​

常见错误 ​

  1. 语法错误

    • 表达式格式不正确
    • 操作符使用错误
    • 括号不匹配

  2. 运行时错误

    • 类型不匹配
    • 空值访问
    • 数组越界

  3. 数据错误

    • 输入格式无效
    • 必需字段缺失
    • 数据类型不符

错误响应 ​

{
  "status": "FAILED",
  "errorMessage": "JQ transformation failed",
  "errorDetails": {
    "reason": "Invalid query expression",
    "expression": ".invalid.path",
    "input": "{...}",
    "error": "Cannot index string with string \"path\""
  }
}

UI 配置指南 ​

  1. 基本设置

    • 选择任务类型
    • 配置任务引用名
    • 设置输入参数

  2. 查询编辑器

    • 使用语法高亮
    • 自动完成支持
    • 实时验证

  3. 测试工具

    • 输入数据预览
    • 查询结果测试
    • 错误信息显示

飞流云

©2025 taskflow, Inc.