mongo-2-sql 0.1.1__tar.gz → 0.1.4__tar.gz

{mongo_2_sql-0.1.1 → mongo_2_sql-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-2-sql
-Version: 0.1.1
+Version: 0.1.4
 Summary: A library to convert MongoDB aggregation pipelines to SQL parser
 Author-email: Bao Bingbo <baob2@outlook.com>
 License: MIT License
@@ -17,12 +17,50 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Requires-Dist: sqlparse>=0.5.5
 Dynamic: license-file
 
 # Mongo to SQL
 
 Mongo to SQL 是一个将 MongoDB 聚合管道转换为 SQL 查询语句的工具。
 
+## 版本更新 v0.1.4
+
+### 新增功能
+
+#### 1. CTE（公用表表达式）统一处理
+- **$addFields、$project、$group 阶段现在使用 CTE 方式处理**
+- 将复杂的聚合管道拆分为多个SQL片段，使用 WITH 子句拼接
+- 自动管理 CTE 命名和依赖关系
+- 适用于多次投影、多层分组等复杂场景
+
+#### 2. 表达式解析器统一架构
+- **ExpressionResolver**: 统一的表达式解析器入口，避免 stage 之间相互 import
+- **BaseExpressionParser**: 基础表达式解析器基类，减少代码重复
+- 提供通用操作符集合、字段引用解析、值转换等基础功能
+
+#### 3. SQL 格式化输出
+- 使用 sqlparse 库自动格式化 SQL
+- SELECT、FROM、WHERE、GROUP BY 等关键字独占一行
+- 字段列表缩进对齐，提高可读性
+- WHERE 子句添加注释提示可扩展性
+
+#### 4. Project 阶段增强
+- 支持字段重命名语法: `{"new_name": "$old_name"}`
+- 聚合后字段引用自动处理（无需添加表前缀）
+- 支持包含模式和排除模式
+
+#### 5. Stage 解耦架构
+- 各 stage 表达式解析器通过统一的 ExpressionResolver 进行交互
+- 避免模块之间的循环依赖
+- 更易于扩展和维护
+
+### 问题修复
+
+- **修复 `_id` 字段双引号问题**: 不再使用 `"_id"`，改为 `_id`
+- **修复聚合后字段引用**: 聚合后的字段不再错误添加表前缀
+- **修复模块导入路径**: 统一使用相对导入，避免 "attempted relative import beyond top-level package" 错误
+
 ## 功能特性
 
 - **阶段基础方法支持**: 支持 `$match`, `$project`, `$group`, `$sort`, `$limit`, `$lookup`, `$unwind` 等常用阶段
@@ -111,6 +149,52 @@ ORDER BY count DESC
 LIMIT 10
 ```
 
+### CTE 处理（复杂聚合管道）
+
+当管道包含多次 $project、$group 或 $addFields 阶段时，系统会自动使用 CTE 方式处理：
+
+```python
+from mongo_2_sql import convert_mongo_pipeline_to_sql
+
+# 复杂管道：多次投影和分组
+pipeline = [
+    { "$match": { "status": "active", "age": { "$gte": 18 } } },
+    { "$project": { "name": 1, "category": 1, "amount": 1 } },
+    { "$group": { "_id": "$category", "totalAmount": { "$sum": "$amount" }, "count": { "$sum": 1 } } },
+    { "$project": { "_id": 1, "totalAmount": 1, "count": 1 } },
+    { "$match": { "totalAmount": { "$gte": 18 } } },
+    { "$sort": { "totalAmount": -1 } },
+    { "$limit": 5 }
+]
+
+sql, metadata = convert_mongo_pipeline_to_sql(pipeline, "transactions")
+print(sql)
+```
+
+输出（自动使用 CTE 格式化）：
+```sql
+WITH cte_1 AS
+  (SELECT t.category AS _id,
+          SUM(t.amount) AS totalAmount,
+          COUNT(*) AS COUNT
+   FROM transactions AS t
+   WHERE 1=1
+     AND (t.status = 'active')
+     AND (t.age >= 18)
+   GROUP BY t.category),
+     cte_2 AS
+  (SELECT t._id AS _id,
+          t.totalAmount AS totalAmount,
+          t.count AS COUNT
+   FROM cte_1 AS t)
+SELECT *
+FROM cte_2 AS t
+WHERE 1=1
+  AND (t.totalAmount >= 18)
+ORDER BY t.totalAmount DESC
+LIMIT 5
+```
+
 ### 面向对象用法
 
 ```python
@@ -297,7 +381,27 @@ FROM products AS t
 GROUP BY t.category
 ```
 
-### 示例 5: 字符串连接
+### 示例 5: 字段重命名
+
+```python
+pipeline = [
+    { 
+        "$project": { 
+            "product_name": "$name",
+            "total_value": { "$multiply": ["$price", "$quantity"] }
+        } 
+    }
+]
+```
+
+```sql
+SELECT 
+    t.name AS product_name,
+    (t.price * t.quantity) AS total_value
+FROM products AS t
+```
+
+### 示例 6: 字符串连接
 
 ```python
 pipeline = [
@@ -319,7 +423,7 @@ SELECT
 FROM users AS t
 ```
 
-### 示例 6: JOIN 查询
+### 示例 7: JOIN 查询
 
 ```python
 pipeline = [
@@ -342,33 +446,6 @@ LEFT JOIN orders AS orders
     ON t._id = orders.customerId
 ```
 
-## 项目结构
-
-```
-mongo_2_sql/
-├── core/                   # 核心模块
-│   ├── ast_base.py        # AST 基础节点
-│   ├── expr_base.py       # 表达式系统
-│   ├── expr_registry.py   # 表达式注册表
-│   ├── stage_base.py      # 阶段处理器基类
-│   ├── stage_loader.py    # 阶段加载器
-│   └── pipeline_runtime.py # 管道运行时
-├── stages/                 # 阶段处理器
-│   ├── match/             # $match 阶段
-│   ├── project/           # $project 阶段
-│   ├── group/             # $group 阶段
-│   ├── sort/              # $sort 阶段
-│   ├── limit/             # $limit/$skip 阶段
-│   ├── lookup/            # $lookup 阶段
-│   └── unwind/            # $unwind 阶段
-├── renderer/               # SQL 渲染器
-│   └── sqlite.py          # SQLite 渲染器
-├── converter.py            # 主要转换入口
-├── main.py                 # 命令行入口
-├── utils.py                # 工具函数
-└── examples.py             # 使用示例
-```
-
 ## 高级特性
 
 ### 自定义阶段处理器
@@ -506,25 +583,26 @@ MIT License - 详见 [LICENSE](LICENSE) 文件
 
 ## 变更日志
 
-### v0.1.0 (2025-02-07)
+### v0.1.4 (2025-02-13)
+
+**新增功能:**
+- CTE 统一处理框架，支持 $addFields、$project、$group 阶段切片
+- ExpressionResolver 统一表达式解析器，避免 stage 间耦合
+- BaseExpressionParser 基础解析器类，减少代码重复
+- SQL 格式化输出（使用 sqlparse）
+- Project 阶段字段重命名支持
+- Stage 解耦架构设计
 
-**新特性:**
-- 初始版本发布
-- 支持基本的 MongoDB 聚合阶段转换
-- 实现 SQLite 方言支持（PostgreSQL、MySQL 需要扩展）
-- 添加命令行工具
+**问题修复:**
+- 修复 `_id` 字段双引号问题
+- 修复聚合后字段引用错误
+- 修复模块导入路径问题
+
+### v0.1.3 (2025-02-07)
 
 **改进:**
-- 优化 SQL 格式化输出
-- 增强错误处理和验证
 - 完善文档和示例
 
-**修复:**
-- 修复 $project 阶段表达式处理问题
-- 修正 WHERE 条件分组逻辑
-- 解决引号处理不一致问题
-- 补充指令操作
-
 ## 致谢
 
 感谢所有贡献者和用户的支持！