# Remote Dyn Filter Implementation Tasks

基于 `/home/discord9/greptimedb_for_build/docs/dyn-filter-propagation-plan-zh.md` 拆分的实现任务文档集合。

统一设计说明见：`remote-dyn-filter-rfc.md`

## 目标

- 将 frontend 产生的 dyn filter 增量传播到 datanode table scan。
- 先用 Phase 1 跑通分布式 `IN` filter 语义，再为后续传输优化与过滤类型扩展留出协议空间。
- 所有任务都以“不影响查询正确性，只影响优化收益”为硬约束。

## 任务清单

1. `remote-dyn-filter-task-01-wire-abi.md`
   - 定义 Dyn Filter 最小 wire contract：identity、payload 边界、版本/epoch 语义与降级规则。
2. `remote-dyn-filter-task-02-region-rpc.md`
   - 在 `RegionRequest.body` 中新增 `remote_dyn_filter` 总入口，并用 `oneof action` 承载 `update / unregister`，打通 frontend -> datanode unary 控制面。
3. `remote-dyn-filter-task-03-frontend-producer.md`
   - 在 frontend 侧识别可分发 dyn filter，完成 filter_id、epoch、目标 region 的生成与下发。
4. `remote-dyn-filter-task-03-minimal-shrink.md`
   - 收缩已经越界的 Task 03：先重写 subtask 06-08 文档，再按最小边界整理 frontend/datanode 相关代码责任。
5. `remote-dyn-filter-task-04-datanode-apply.md`
   - 在 datanode 侧维护 query-scoped filter state，并将 update 应用到 scan predicate。
6. `remote-dyn-filter-task-05-observability-fallback.md`
   - 增加 metrics、tracing、TTL 清理、错误降级与控制面保护。
7. `remote-dyn-filter-task-06-validation.md`
   - 完成功能、一致性、可靠性、性能验证，并为 Phase 2/3 演进保留回归基线。
8. `remote-dyn-filter-task-07-large-build-membership.md`
   - 为 large build-side equal join 的 lookup-like membership 设计远端可传输表示，重点覆盖 `HashTableLookupExpr` 无法直接序列化的问题。

## 建议执行顺序

1. 先完成 ABI 定义，避免 RPC 和状态机实现反复返工。
2. 然后基于 `RegionRequest.body.remote_dyn_filter` 打通 unary RPC 请求链路，让 frontend 和 datanode 拥有最小控制面，并把 dyn filter 操作扩展点统一收敛到 `RemoteDynFilterRequest.oneof action`。
3. 若 Task 03 的实现已经漂出最小边界，先执行 `remote-dyn-filter-task-03-minimal-shrink.md`，再继续推进 Task 03 / Task 04。
4. 接着分别实现 frontend 生产者和 datanode 消费者，完成端到端语义闭环。
5. 最后补齐观测性、清理、降级和测试，确保该优化在失败时能自动失效而不是破坏查询。

## 完整工作流程（Phase 1）

1. **frontend 发现可下推 dyn filter**
   - 在 `MergeScanExec` 所在查询树上，DataFusion 调用 `gather_filters_for_pushdown` 时会把当前可下推的 dyn filters 暴露给下游 scan。
   - 这一刻是 frontend 侧为 remote dyn filter 建立注册关系的最佳时机：记录 `query_id + filter_id` 这一逻辑 filter identity，并维护它当前订阅了哪些 remote region/scan，同时保存对应本地 `DynamicFilterPhysicalExpr` 的引用。
2. **初始 remote read 负责把“会有这个 dyn filter”这件事带到 datanode**
   - 后续 `MergeScanExec::to_stream` 发起 remote read 时，仍然带着同一个 `query_id` 与目标 region/scan 身份。
   - datanode 在接收初始请求并构建 scan 时，为这些即将接收远端更新的 dyn filters 建立注册项，并安装 placeholder / remote wrapper。
3. **frontend 持续观察 dyn filter 更新并转成远端 update**
   - frontend 注册中心通过本地 dyn filter 的更新通知（例如 `wait_update` / generation 变化）感知新快照。
   - 每次有新快照时，frontend 将其编码为 `DynFilterUpdate`，并通过 Task 02 定义的 unary RPC 发送给对应 datanode。
4. **datanode 注册中心接收 update 并刷新本地 dyn filter**
   - datanode 根据 `query_id + filter_id` 找到共享的 remote filter state，并把 update 分发给当前挂接在该 state 上的本地 consumer / wrapper 视图。
   - 若 epoch 更大则应用更新，若重复/过期则按幂等规则安全忽略。
   - scan 在后续 pruning / predicate 计算时读取 wrapper 当前快照，从而渐进增强裁剪收益。
5. **frontend 负责判定“这个 dyn filter 在本查询里是否已无人使用”**
   - 对 frontend 本地持有的 `DynamicFilterPhysicalExpr`，`is_used()` 可作为“该查询内是否仍有 consumer 在使用这个 dyn filter”的判据。
   - 一旦 frontend 确认该 dyn filter 在本查询中已无人使用，就可以把它从 frontend 注册中心注销，并通知相关 datanode 注销对应注册项。
   - datanode 侧也可以把本地 remote wrapper / `DynamicFilterPhysicalExpr` 的 `is_used()` 作为“当前节点上是否还有 scan consumer”的快速判据，用于 eager local cleanup；但它只是正常清理的补充信号，不替代显式 unregister / cancel / TTL。
6. **异常和兜底清理**
   - `is_used()` 触发的是正常路径下的前端注销信号；异常断连、query cancel、frontend 崩溃等场景仍需依赖显式 cancel/complete 和 datanode TTL 兜底。

## 实施前先澄清的契约

- 初始 remote read 请求必须携带与后续 dyn filter update 相同的 `query_id + filter_id` 逻辑 identity；region/scan 只承担注册与路由元数据，不再是 filter state identity 的一部分。
- datanode 需要明确定义“update 早于 scan 注册到达”时的行为，Phase 1 应至少固定为缓冲、显式丢弃加指标、或前端重试中的一种。
- `is_final` 仅表示后续不会再有更强 update，不等于可立即删除最终 filter state；真正回收仍以 query finish / cancel / TTL 为准。
- query-scoped filter state 的生命周期与清理责任以 Task 04 为主，Task 05 只补充观测、预算和兜底机制。

## Phase 对应关系

- Task 01-06 覆盖 Phase 1 的最小可用版本。
- Task 05 和 Task 06 同时为 Phase 2 的 batched update、ack、watermark、heartbeat 做准备。
- Phase 3 的 `MIN_MAX` / `BLOOM` 只需要在 Task 01 预留 ABI 扩展点，再在后续增量任务中落地。
- Task 07 是一个独立的后续任务，面向“大 build side equal join membership”的远端表示设计，更接近 Phase 2/3 的增强项。