Hi all, I’d like to introduce a refactoring in PR #17526: https://github.com/apache/iotdb/pull/17526
This PR reorganizes part of the query planning stack to make common query abstractions reusable across modules, without requiring a dependency on the datanode module. ------------------------------ Why This Matters Currently, several core query planning abstractions—such as PlanNode, common query operators, and visitor logic—are located inside the datanode module. This creates an unnecessary dependency constraint: even if another module only needs the query model or planning abstractions, it must still depend on the entire datanode. By decoupling these reusable components, we can: - Enable other modules to depend directly on PlanNode and common query abstractions - Reduce unnecessary module dependencies - Provide a cleaner and more maintainable dependency structure - Improve extensibility for future query-related components ------------------------------ Main Changes - *Extracted PlanNode abstractions*: Moved reusable PlanNode-related classes from datanode into common/shared modules - *Decoupled visitor framework*: Made common query visitor abstractions available outside of datanode - *Exposed reusable operators*: Promoted common query operators and planner-side components as reusable dependencies - *Clarified module boundaries*: Kept execution/runtime-specific logic within datanode, separating it from the reusable query model - *Documented visitor contract*: Added documentation and tests to make the current visitor assumptions explicit and prevent accidental breakage ------------------------------ Impact This is primarily a *dependency-boundary refactor*; query planning and execution behavior should remain unchanged. Other modules can now depend directly on PlanNode and common query components without pulling in datanode. Some package structures have changed, so downstream code may need to update imports. The existing visitor contract is preserved. In particular, some PlanNode.accept(...) paths still assume visitors belong to the core query visitor hierarchy. This is now explicitly documented and covered by tests. This refactor should make future modularization and reuse of query components easier. ------------------------------ Potential Risks Although intended to be behavior-preserving, this change touches core query planning abstractions and may affect compile-time dependencies or internal integrations. Code relying on previous package locations may need adjustment. The current visitor contract remains somewhat fragile, especially around PlanNode.accept(...), and may need further generalization in the future. ------------------------------ This email is mainly a heads-up since the refactor changes module boundaries in the query stack and is intended to support future reuse. Feedback and suggestions are very welcome. ------------------------------ 大家好， 我想介绍一个在 PR #17526 中进行的重构： https://github.com/apache/iotdb/pull/17526 该 PR 对查询规划相关的部分结构进行了重组，使通用查询抽象可以在多个模块之间复用，而无需依赖 datanode 模块。 ------------------------------ 为什么这个改动很重要 目前，一些核心查询规划抽象（如 PlanNode、通用查询算子和 visitor 逻辑）都位于 datanode 模块中。 这会带来不必要的依赖约束：即使其他模块只需要查询模型或规划抽象，也必须依赖整个 datanode 模块。 通过将这些可复用组件解耦，我们可以： - 让其他模块可以直接依赖 PlanNode 和通用查询抽象 - 减少不必要的模块依赖 - 提供更清晰、更易维护的依赖结构 - 提高未来查询相关组件的扩展性 ------------------------------ 主要改动 - *抽取 PlanNode 抽象*：将可复用的 PlanNode 相关类从 datanode 移动到公共模块 - *解耦 visitor 框架*：使通用查询 visitor 抽象可以在 datanode 之外使用 - *开放可复用算子*：将通用查询算子和规划阶段组件作为可复用依赖提供 - *明确模块边界*：将执行和运行时相关逻辑保留在 datanode 中，与可复用的查询模型进行分离 - *补充 visitor 约束说明*：增加文档和测试，使当前 visitor 的约束更加明确，并防止后续重构时被破坏 ------------------------------ 影响 该改动主要是*依赖边界的重构*，查询规划和执行行为应保持不变。 其他模块现在可以直接依赖 PlanNode 和通用查询组件，而无需引入 datanode。 部分包结构发生变化，下游代码可能需要更新 import。 现有的 visitor 约束保持不变，特别是部分 PlanNode.accept(...) 路径仍然假设 visitor 属于核心查询 visitor 体系。 这一点已经通过文档和测试明确说明。 该重构将有助于未来查询组件的模块化和复用。 ------------------------------ 潜在风险 虽然该改动旨在保持行为不变，但由于涉及核心查询规划抽象，可能会影响编译期依赖或内部集成。 依赖旧包路径的代码可能需要调整。 当前 visitor 约束仍然相对脆弱，尤其是在 PlanNode.accept(...) 相关路径上，未来可能需要进一步泛化。 ------------------------------ 这封邮件主要是提前告知，因为该重构涉及查询栈的模块边界调整，并旨在支持未来的复用。 欢迎大家提出反馈和建议。 Best regards, Wenwei Shu
