用途:streamling transform 位于管道中间,接收上游 RecordBatch,返回(可能改变结构的)RecordBatch,并传播检查点。默认是无状态按行流水线,适用于内置 sql 转换无法表达的逻辑,例如自定义 Rust、逐行外部调用、非 SQL 投影。前置技能:streamling-plugin-basics(crate 搭建、注册、生命周期、错误处理)。不适用场景:列投影/重命名、UNION ALL、JOIN 用内置 type: sql(DataFusion)更简单更快;仅在需要命令式 Rust 或 SQL 引擎无法完成的副作用时才写插件转换。
主要能力与用法:实现 TransformPlugin trait,核心方法为 initialize、output_schema、process_batch、process_checkpoint_marker、process_checkpoint_finalizer,构造器由 register_plugin_transform! 调用,参数含 schema、运行时、状态后端工厂、指标记录器与 options。output_schema 可选择透传(过滤、原地增强返回输入 schema)或重塑(增删改列时在 new() 中一次构建并返回新 schema,下游按此读取)。process_batch 的契约是 RecordBatch 进 RecordBatch 出:空入必须空出,先处理 num_rows()==0 并原样返回;返回 Err 会使管道失败,逐行软失败应输出 null 或丢弃该行。常用模式包括用 BooleanArray 掩码配合 filter_record_batch 做行过滤(多条件从全 true 开始用 and 折叠,空值为假);用 StringBuilder、Int64Builder 等构建新数组并 RecordBatch::try_new 增加派生列;需要跨批记忆(运行聚合、去重集合)时使用状态后端,在 initialize 恢复、process_batch 修改、process_checkpoint_finalizer 持久化。除非自己持有持久状态,检查点方法应为空操作返回 Ok(()) 以向下游传播标记。背压可通过 set_plugin_output_buffer!("my_plugin.filter", 1) 限制输出通道。
常见错误:忘记空批次保护;输出 schema 与实际返回批次不一致;坏行导致 panic(应转为 PluginError::Execution);因单行问题让整批失败;重复实现 SQL。相关技能:streamling-plugin-basics、sql-transform、streamling-udf-plugin。安装命令、收费与价格信息暂未提供。