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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mongo-2-sql
-Version: 0.1.3
+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 = [
@@ -479,6 +583,21 @@ MIT License - 详见 [LICENSE](LICENSE) 文件
 
 ## 变更日志
 
+### v0.1.4 (2025-02-13)
+
+**新增功能:**
+- CTE 统一处理框架，支持 $addFields、$project、$group 阶段切片
+- ExpressionResolver 统一表达式解析器，避免 stage 间耦合
+- BaseExpressionParser 基础解析器类，减少代码重复
+- SQL 格式化输出（使用 sqlparse）
+- Project 阶段字段重命名支持
+- Stage 解耦架构设计
+
+**问题修复:**
+- 修复 `_id` 字段双引号问题
+- 修复聚合后字段引用错误
+- 修复模块导入路径问题
+
 ### v0.1.3 (2025-02-07)
 
 **改进:**