优化项目整合内容

modules/query_engine.py

@@ -1,6 +1,35 @@
 """
-数据查询模块
-负责Cassandra数据的查询执行，支持单表、分表和多主键查询
+数据查询引擎模块
+================
+
+本模块是BigDataTool的核心查询引擎，负责Cassandra数据库的高级查询功能。
+
+核心功能：
+1. 单表查询：标准的Cassandra CQL查询执行
+2. 分表查询：基于TWCS策略的时间分表查询
+3. 多主键查询：支持复合主键的复杂查询条件
+4. 混合查询：生产环境分表+测试环境单表的组合查询
+
+查询类型支持：
+- 单主键查询：WHERE key IN (val1, val2, val3)
+- 复合主键查询：WHERE (key1='val1' AND key2='val2') OR (key1='val3' AND key2='val4')
+- 分表查询：自动计算分表名称并并行查询多张表
+- 字段过滤：支持指定查询字段和排除字段
+
+分表查询特性：
+- 时间戳提取：从Key中智能提取时间戳信息
+- 分表计算：基于TWCS策略计算目标分表
+- 并行查询：同时查询多张分表以提高性能
+- 错误容错：单个分表查询失败不影响整体结果
+
+性能优化：
+- 查询时间监控：记录每个查询的执行时间
+- 批量处理：支持大批量Key的高效查询
+- 连接复用：优化数据库连接的使用
+- 内存管理：大结果集的内存友好处理
+
+作者：BigDataTool项目组
+更新时间：2024年8月
 """
 
 import time
@@ -10,7 +39,39 @@ from .sharding import ShardingCalculator
 logger = logging.getLogger(__name__)
 
 def execute_query(session, table, keys, fields, values, exclude_fields=None):
-    """执行查询，支持单主键和复合主键"""
+    """
+    执行Cassandra数据库查询，支持单主键和复合主键查询
+
+    本函数是查询引擎的核心，能够智能处理不同类型的主键查询：
+    - 单主键：生成 WHERE key IN (val1, val2, val3) 查询
+    - 复合主键：生成 WHERE (key1='val1' AND key2='val2') OR ... 查询
+
+    Args:
+        session: Cassandra数据库会话对象
+        table (str): 目标表名
+        keys (list): 主键字段名列表，如 ['id'] 或 ['docid', 'id']
+        fields (list): 要查询的字段列表，空列表表示查询所有字段
+        values (list): 查询值列表，复合主键值用逗号分隔
+        exclude_fields (list, optional): 要排除的字段列表
+
+    Returns:
+        list: 查询结果列表，每个元素是一个Row对象
+
+    查询示例：
+        # 单主键查询
+        execute_query(session, 'users', ['id'], ['name', 'email'], ['1', '2', '3'])
+        # 生成SQL: SELECT name, email FROM users WHERE id IN ('1', '2', '3')
+
+        # 复合主键查询
+        execute_query(session, 'orders', ['user_id', 'order_id'], ['*'], ['1,100', '2,200'])
+        # 生成SQL: SELECT * FROM orders WHERE (user_id='1' AND order_id='100') OR (user_id='2' AND order_id='200')
+
+    错误处理：
+        - 参数验证：检查keys和values是否为空
+        - SQL注入防护：对查询值进行适当转义
+        - 异常捕获：数据库错误时返回空列表
+        - 日志记录：记录查询SQL和执行统计
+    """
     try:
         # 参数验证
         if not keys or len(keys) == 0: