quantnodes 3.0.0__py3-none-any.whl

QuantNodes/symbolic/__init__.py

@@ -0,0 +1,51 @@
+# coding=utf-8
+"""
+符号计算引擎
+
+提供表达式到 SQL 的编译能力，支持多种数据库方言。
+"""
+
+from QuantNodes.symbolic.dialect import (
+    DialectType,
+    SQLDialect,
+    ClickHouseDialect,
+    DuckDBDialect,
+    MySQLDialect,
+)
+from QuantNodes.symbolic.compiler import SQLCompiler, compile_expression
+from QuantNodes.symbolic.expression import (
+    SQLExpression,
+    ColumnRef,
+    LiteralValue,
+    SQLBinaryOp,
+    SQLUnaryOp,
+    SQLComparison,
+    SQLLogicalOp,
+    SQLFunction,
+    SQLCase,
+)
+from QuantNodes.symbolic.functions import (
+    TechnicalFunctions,
+    TA_FUNCTIONS,
+)
+
+__all__ = [
+    "DialectType",
+    "SQLDialect",
+    "ClickHouseDialect",
+    "DuckDBDialect",
+    "MySQLDialect",
+    "SQLCompiler",
+    "compile_expression",
+    "SQLExpression",
+    "ColumnRef",
+    "LiteralValue",
+    "SQLBinaryOp",
+    "SQLUnaryOp",
+    "SQLComparison",
+    "SQLLogicalOp",
+    "SQLFunction",
+    "SQLCase",
+    "TechnicalFunctions",
+    "TA_FUNCTIONS",
+]

QuantNodes/symbolic/compiler.py

@@ -0,0 +1,113 @@
+# coding=utf-8
+"""
+符号计算引擎 - SQL 编译器
+
+使用 Visitor 模式将 SQLExpression AST 编译为 SQL 字符串。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+
+if TYPE_CHECKING:
+    from QuantNodes.symbolic.dialect import SQLDialect
+    from QuantNodes.symbolic.expression import SQLExpression
+
+
+class SQLCompiler:
+    """
+    SQL 编译器
+
+    将 SQLExpression AST 编译为 SQL 字符串。
+
+    Examples:
+        >>> from QuantNodes.symbolic import ClickHouseDialect, ColumnRef, SQLBinaryOp
+        >>> compiler = SQLCompiler(ClickHouseDialect())
+        >>> expr = ColumnRef("close") + ColumnRef("open")
+        >>> sql = compiler.compile(expr)
+        >>> print(sql)
+        (`close` + `open`)
+    """
+
+    def __init__(self, dialect: "SQLDialect"):
+        self.dialect = dialect
+        self._context: Dict[str, Any] = {}
+
+    def compile(self, expr: "SQLExpression") -> str:
+        """编译表达式为 SQL 字符串"""
+        return expr.to_sql(self.dialect)
+
+    def compile_to_select(
+        self,
+        columns: List["SQLExpression"],
+        table: str,
+        where: Optional["SQLExpression"] = None,
+        group_by: Optional[List["SQLExpression"]] = None,
+        having: Optional["SQLExpression"] = None,
+        order_by: Optional[List[Tuple["SQLExpression", str]]] = None,
+        limit: Optional[int] = None,
+    ) -> str:
+        """编译为完整 SELECT 语句"""
+        col_sqls = [col.to_sql(self.dialect) for col in columns]
+        cols_str = ", ".join(col_sqls)
+
+        table_sql = self.dialect.quote_identifier(table)
+
+        sql_parts = [f"SELECT {cols_str}", f"FROM {table_sql}"]
+
+        if where is not None:
+            sql_parts.append(f"WHERE {where.to_sql(self.dialect)}")
+
+        if group_by is not None:
+            group_sqls = [g.to_sql(self.dialect) for g in group_by]
+            sql_parts.append(f"GROUP BY {', '.join(group_sqls)}")
+
+        if having is not None:
+            sql_parts.append(f"HAVING {having.to_sql(self.dialect)}")
+
+        if order_by is not None:
+            order_sqls = []
+            for expr, direction in order_by:
+                order_sqls.append(f"{expr.to_sql(self.dialect)} {direction}")
+            sql_parts.append(f"ORDER BY {', '.join(order_sqls)}")
+
+        if limit is not None:
+            sql_parts.append(f"LIMIT {limit}")
+
+        return " ".join(sql_parts)
+
+
+def compile_expression(
+    expr: "SQLExpression",
+    dialect: Optional["SQLDialect"] = None,
+    dialect_type: Optional[str] = None,
+) -> str:
+    """
+    便捷函数：编译表达式为 SQL 字符串
+
+    Args:
+        expr: SQL 表达式
+        dialect: SQL 方言实例
+        dialect_type: 方言类型名称 (clickhouse/duckdb/mysql)
+
+    Returns:
+        SQL 字符串
+    """
+    if dialect is None and dialect_type is None:
+        from QuantNodes.symbolic.dialect import ClickHouseDialect
+        dialect = ClickHouseDialect()
+    elif dialect is None and dialect_type is not None:
+        dialect_map = {
+            "clickhouse": "ClickHouseDialect",
+            "duckdb": "DuckDBDialect",
+            "mysql": "MySQLDialect",
+        }
+        dialect_name = dialect_map.get(dialect_type.lower())
+        if dialect_name is None:
+            raise ValueError(f"Unknown dialect type: {dialect_type}")
+        from QuantNodes.symbolic.dialect import ClickHouseDialect, DuckDBDialect, MySQLDialect  # noqa: F401
+        dialect_cls = locals()[dialect_name]
+        dialect = dialect_cls()
+
+    compiler = SQLCompiler(dialect)
+    return compiler.compile(expr)

QuantNodes/symbolic/dialect.py

@@ -0,0 +1,260 @@
+# coding=utf-8
+"""符号计算引擎 - 数据库方言抽象"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, List, Optional, Tuple
+
+class DialectType(Enum):
+    CLICKHOUSE = "clickhouse"
+    DUCKDB = "duckdb"
+    MYSQL = "mysql"
+    POSTGRESQL = "postgresql"
+
+class SQLDialect(ABC):
+    dialect_name: DialectType
+    @abstractmethod
+    def quote_identifier(self, name: str) -> str: pass
+    @abstractmethod
+    def quote_literal(self, value: Any) -> str: pass
+    @abstractmethod
+    def func_now(self) -> str: pass
+    @abstractmethod
+    def func_date_diff(self, unit: str, start: str, end: str) -> str: pass
+    @abstractmethod
+    def func_coalesce(self, *args: str) -> str: pass
+    @abstractmethod
+    def func_ifnull(self, expr: str, default: str) -> str: pass
+    @abstractmethod
+    def func_if(self, condition: str, then: str, else_: str) -> str: pass
+    @abstractmethod
+    def func_case(self, when_clauses: List[Tuple[str, str]], else_: Optional[str] = None) -> str: pass
+    @abstractmethod
+    def func_cast(self, expr: str, target_type: str) -> str: pass
+    @abstractmethod
+    def func_interval(self, value: str, unit: str) -> str: pass
+    @abstractmethod
+    def is_distinct_from(self, a: str, b: str) -> str: pass
+    @abstractmethod
+    def is_not_distinct_from(self, a: str, b: str) -> str: pass
+    @abstractmethod
+    def func_rank(self) -> str: pass
+    @abstractmethod
+    def func_dense_rank(self) -> str: pass
+    @abstractmethod
+    def func_row_number(self) -> str: pass
+    @abstractmethod
+    def func_lag(self, expr: str, offset: int, default: Optional[str] = None) -> str: pass
+    @abstractmethod
+    def func_lead(self, expr: str, offset: int, default: Optional[str] = None) -> str: pass
+    @abstractmethod
+    def func_avg(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_sum(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_max(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_min(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_count(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_stddev(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_variance(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_quantile(self, expr: str, quantile: float) -> str: pass
+    @abstractmethod
+    def func_abs(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_ceil(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_floor(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_round(self, expr: str, decimals: int = 0) -> str: pass
+    @abstractmethod
+    def func_pow(self, expr: str, power: float) -> str: pass
+    @abstractmethod
+    def func_sqrt(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_ln(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_log10(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_cumsum(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_running_diff(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_length(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_concat(self, *args: str) -> str: pass
+    @abstractmethod
+    def func_upper(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_lower(self, expr: str) -> str: pass
+    @abstractmethod
+    def func_substring(self, expr: str, start: int, length: Optional[int] = None) -> str: pass
+    @abstractmethod
+    def parse_datetime(self, expr: str, format: str) -> str: pass
+    @abstractmethod
+    def extract_date_part(self, expr: str, part: str) -> str: pass
+class BaseSQLDialect(SQLDialect):
+    def func_case(self, when_clauses: List[Tuple[str, str]], else_: Optional[str] = None) -> str:
+        parts = ["CASE WHEN " + cond + " THEN " + val for cond, val in when_clauses]
+        if else_:
+            parts.append("ELSE " + else_)
+        parts.append("END")
+        return " ".join(parts)
+
+    def func_cast(self, expr: str, target_type: str) -> str:
+        return "CAST(" + expr + " AS " + target_type + ")"
+
+    def func_rank(self) -> str: return "rank()"
+    def func_dense_rank(self) -> str: return "dense_rank()"
+    def func_row_number(self) -> str: return "row_number()"
+    def func_avg(self, expr: str) -> str: return "avg(" + expr + ")"
+    def func_sum(self, expr: str) -> str: return "sum(" + expr + ")"
+    def func_max(self, expr: str) -> str: return "max(" + expr + ")"
+    def func_min(self, expr: str) -> str: return "min(" + expr + ")"
+    def func_count(self, expr: str) -> str: return "count(" + expr + ")"
+    def func_abs(self, expr: str) -> str: return "abs(" + expr + ")"
+    def func_floor(self, expr: str) -> str: return "floor(" + expr + ")"
+    def func_round(self, expr: str, decimals: int = 0) -> str: return "round(" + expr + ", " + str(decimals) + ")"
+    def func_pow(self, expr: str, power: float) -> str: return "pow(" + expr + ", " + str(power) + ")"
+    def func_sqrt(self, expr: str) -> str: return "sqrt(" + expr + ")"
+    def func_concat(self, *args: str) -> str: return "concat(" + ", ".join(args) + ")"
+    def func_upper(self, expr: str) -> str: return "upper(" + expr + ")"
+    def func_lower(self, expr: str) -> str: return "lower(" + expr + ")"
+
+    def func_substring(self, expr: str, start: int, length: Optional[int] = None) -> str:
+        if length is not None:
+            return "substring(" + expr + ", " + str(start) + ", " + str(length) + ")"
+        return "substring(" + expr + ", " + str(start) + ")"
+
+class ClickHouseDialect(BaseSQLDialect):
+    dialect_name = DialectType.CLICKHOUSE
+
+    def quote_identifier(self, name: str) -> str: return "`" + name + "`"
+
+    def quote_literal(self, value: Any) -> str:
+        if value is None: return "NULL"
+        if isinstance(value, str): return "'" + value.replace("'", "\'\'") + "'"
+        if isinstance(value, bool): return "1" if value else "0"
+        return str(value)
+
+    def func_now(self) -> str: return "now()"
+    def func_date_diff(self, unit: str, start: str, end: str) -> str: return "dateDiff('" + unit + "', " + start + ", " + end + ")"
+    def func_coalesce(self, *args: str) -> str: return "coalesce(" + ", ".join(args) + ")"
+    def func_ifnull(self, expr: str, default: str) -> str: return "ifNull(" + expr + ", " + default + ")"
+    def func_if(self, condition: str, then: str, else_: str) -> str: return "if(" + condition + ", " + then + ", " + else_ + ")"
+    def func_interval(self, value: str, unit: str) -> str: return "INTERVAL " + value + " " + unit
+    def is_distinct_from(self, a: str, b: str) -> str: return a + " IS DISTINCT FROM " + b
+    def is_not_distinct_from(self, a: str, b: str) -> str: return a + " IS NOT DISTINCT FROM " + b
+
+    def func_lag(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "lagInFrame(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "lagInFrame(" + expr + ", " + str(offset) + ")"
+
+    def func_lead(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "leadInFrame(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "leadInFrame(" + expr + ", " + str(offset) + ")"
+
+    def func_stddev(self, expr: str) -> str: return "stddevPop(" + expr + ")"
+    def func_variance(self, expr: str) -> str: return "varPop(" + expr + ")"
+    def func_quantile(self, expr: str, quantile: float) -> str: return "quantile(" + str(quantile) + ")(" + expr + ")"
+    def func_ceil(self, expr: str) -> str: return "ceil(" + expr + ")"
+    def func_ln(self, expr: str) -> str: return "log(" + expr + ")"
+    def func_log10(self, expr: str) -> str: return "log10(" + expr + ")"
+    def func_cumsum(self, expr: str) -> str: return "sum(" + expr + ")"
+    def func_running_diff(self, expr: str) -> str: return "runningDifference(" + expr + ")"
+    def func_length(self, expr: str) -> str: return "length(" + expr + ")"
+    def parse_datetime(self, expr: str, format: str) -> str: return "parseDateTime(" + expr + ", '" + format + "')"
+    def extract_date_part(self, expr: str, part: str) -> str: return "extract(" + part + " FROM " + expr + ")"
+
+class DuckDBDialect(BaseSQLDialect):
+    dialect_name = DialectType.DUCKDB
+
+    def quote_identifier(self, name: str) -> str: return '"' + name + '"'
+
+    def quote_literal(self, value: Any) -> str:
+        if value is None: return "NULL"
+        if isinstance(value, str): return "'" + value.replace("'", "''") + "'"
+        if isinstance(value, bool): return "TRUE" if value else "FALSE"
+        return str(value)
+
+    def func_now(self) -> str: return "now()"
+    def func_date_diff(self, unit: str, start: str, end: str) -> str: return "datediff('" + unit + "', " + start + ", " + end + ")"
+    def func_coalesce(self, *args: str) -> str: return "coalesce(" + ", ".join(args) + ")"
+    def func_ifnull(self, expr: str, default: str) -> str: return "ifnull(" + expr + ", " + default + ")"
+    def func_if(self, condition: str, then: str, else_: str) -> str: return "if(" + condition + ", " + then + ", " + else_ + ")"
+    def func_interval(self, value: str, unit: str) -> str: return "INTERVAL '" + value + "' " + unit
+    def is_distinct_from(self, a: str, b: str) -> str: return a + " IS DISTINCT FROM " + b
+    def is_not_distinct_from(self, a: str, b: str) -> str: return a + " IS NOT DISTINCT FROM " + b
+
+    def func_lag(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "lag(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "lag(" + expr + ", " + str(offset) + ")"
+
+    def func_lead(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "lead(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "lead(" + expr + ", " + str(offset) + ")"
+
+    def func_stddev(self, expr: str) -> str: return "stddev_pop(" + expr + ")"
+    def func_variance(self, expr: str) -> str: return "var_pop(" + expr + ")"
+    def func_quantile(self, expr: str, quantile: float) -> str: return "quantile_cont(" + expr + ", " + str(quantile) + ")"
+    def func_ceil(self, expr: str) -> str: return "ceil(" + expr + ")"
+    def func_ln(self, expr: str) -> str: return "ln(" + expr + ")"
+    def func_log10(self, expr: str) -> str: return "log10(" + expr + ")"
+    def func_cumsum(self, expr: str) -> str: return "sum(" + expr + ")"
+    def func_running_diff(self, expr: str) -> str: return expr + " - lag(" + expr + ", 1)"
+    def func_length(self, expr: str) -> str: return "length(" + expr + ")"
+    def parse_datetime(self, expr: str, format: str) -> str: return "strptime(" + expr + ", '" + format + "')"
+    def extract_date_part(self, expr: str, part: str) -> str: return "date_part('" + part + "', " + expr + ")"
+
+class MySQLDialect(BaseSQLDialect):
+    dialect_name = DialectType.MYSQL
+
+    def quote_identifier(self, name: str) -> str: return "`" + name + "`"
+
+    def quote_literal(self, value: Any) -> str:
+        if value is None: return "NULL"
+        if isinstance(value, str): return "'" + value.replace("'", "''") + "'"
+        if isinstance(value, bool): return "1" if value else "0"
+        return str(value)
+
+    def func_now(self) -> str: return "NOW()"
+    def func_date_diff(self, unit: str, start: str, end: str) -> str: return "DATEDIFF(" + end + ", " + start + ")"
+    def func_coalesce(self, *args: str) -> str: return "COALESCE(" + ", ".join(args) + ")"
+    def func_ifnull(self, expr: str, default: str) -> str: return "IFNULL(" + expr + ", " + default + ")"
+    def func_if(self, condition: str, then: str, else_: str) -> str: return "IF(" + condition + ", " + then + ", " + else_ + ")"
+    def func_interval(self, value: str, unit: str) -> str: return "INTERVAL " + value + " " + unit
+
+    def is_distinct_from(self, a: str, b: str) -> str:
+        return "(" + a + " IS NULL AND " + b + " IS NOT NULL OR " + a + " IS NOT NULL AND " + b + " IS NULL OR " + a + " <> " + b + ")"
+
+    def is_not_distinct_from(self, a: str, b: str) -> str:
+        return "(" + a + " IS NULL AND " + b + " IS NULL OR " + a + " = " + b + ")"
+
+    def func_lag(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "LAG(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "LAG(" + expr + ", " + str(offset) + ")"
+
+    def func_lead(self, expr: str, offset: int, default: Optional[str] = None) -> str:
+        if default is not None: return "LEAD(" + expr + ", " + str(offset) + ", " + default + ")"
+        return "LEAD(" + expr + ", " + str(offset) + ")"
+
+    def func_stddev(self, expr: str) -> str: return "STDDEV_POP(" + expr + ")"
+    def func_variance(self, expr: str) -> str: return "VAR_POP(" + expr + ")"
+    def func_quantile(self, expr: str, quantile: float) -> str: return "QUANTILE_CONT(" + expr + ", " + str(quantile) + ")"
+    def func_ceil(self, expr: str) -> str: return "CEILING(" + expr + ")"
+    def func_ln(self, expr: str) -> str: return "LN(" + expr + ")"
+    def func_log10(self, expr: str) -> str: return "LOG10(" + expr + ")"
+    def func_cumsum(self, expr: str) -> str: return "SUM(" + expr + ")"
+    def func_running_diff(self, expr: str) -> str: return expr + " - LAG(" + expr + ", 1)"
+    def func_length(self, expr: str) -> str: return "LENGTH(" + expr + ")"
+    def func_upper(self, expr: str) -> str: return "UPPER(" + expr + ")"
+    def func_lower(self, expr: str) -> str: return "LOWER(" + expr + ")"
+    def func_substring(self, expr: str, start: int, length: Optional[int] = None) -> str:
+        if length is not None: return "SUBSTRING(" + expr + ", " + str(start) + ", " + str(length) + ")"
+        return "SUBSTRING(" + expr + ", " + str(start) + ")"
+    def parse_datetime(self, expr: str, format: str) -> str: return "STR_TO_DATE(" + expr + ", '" + format + "')"
+    def extract_date_part(self, expr: str, part: str) -> str: return "EXTRACT(" + part + " FROM " + expr + ")"

QuantNodes/symbolic/executor.py

@@ -0,0 +1,147 @@
+# coding=utf-8
+"""
+符号计算引擎 - 执行引擎
+
+在数据库上执行编译后的 SQL 表达式。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    import pandas as pd
+    from QuantNodes.symbolic.compiler import SQLCompiler
+    from QuantNodes.symbolic.expression import SQLExpression
+
+
+class SQLExecutor:
+    """
+    SQL 执行引擎
+
+    在数据库连接上执行编译后的 SQL。
+
+    Examples:
+        >>> from QuantNodes.symbolic import ClickHouseDialect, SQLExecutor
+        >>> from QuantNodes.symbolic.expression import ColumnRef
+        >>> executor = SQLExecutor(db_connection, ClickHouseDialect())
+        >>> result = executor.execute("SELECT * FROM t")
+    """
+
+    def __init__(
+        self,
+        connection: Any,
+        compiler: Optional["SQLCompiler"] = None,
+        dialect: Optional["SQLDialect"] = None,  # noqa: F821
+    ):
+        """
+        Args:
+            connection: 数据库连接对象
+            compiler: SQL 编译器实例
+            dialect: SQL 方言 (如果 compiler 为 None)
+        """
+        self.connection = connection
+        if compiler is not None:
+            self.compiler = compiler
+        elif dialect is not None:
+            from QuantNodes.symbolic.compiler import SQLCompiler
+            self.compiler = SQLCompiler(dialect)
+        else:
+            from QuantNodes.symbolic.dialect import ClickHouseDialect
+            from QuantNodes.symbolic.compiler import SQLCompiler
+            self.compiler = SQLCompiler(ClickHouseDialect())
+
+    def execute(
+        self,
+        sql: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> "pd.DataFrame":
+        """
+        执行 SQL 查询
+
+        Args:
+            sql: SQL 字符串
+            params: 查询参数
+
+        Returns:
+            DataFrame 结果
+        """
+        import pandas as pd
+
+        cursor = self.connection.cursor()
+
+        if params:
+            cursor.execute(sql, params)
+        else:
+            cursor.execute(sql)
+
+        if cursor.description:
+            columns = [desc[0] for desc in cursor.description]
+            rows = cursor.fetchall()
+            return pd.DataFrame(rows, columns=columns)
+
+        return pd.DataFrame()
+
+    def execute_expression(
+        self,
+        expr: "SQLExpression",
+        table: str,
+        columns: Optional[List["SQLExpression"]] = None,
+        where: Optional["SQLExpression"] = None,
+        group_by: Optional[List["SQLExpression"]] = None,
+        having: Optional["SQLExpression"] = None,
+        order_by: Optional[List] = None,
+        limit: Optional[int] = None,
+    ) -> "pd.DataFrame":
+        """
+        执行表达式
+
+        Args:
+            expr: SQL 表达式
+            table: 表名
+            columns: 选择列
+            where: WHERE 条件
+            group_by: GROUP BY 列
+            having: HAVING 条件
+            order_by: ORDER BY 列
+            limit: LIMIT
+
+        Returns:
+            DataFrame 结果
+        """
+        if columns is None:
+            columns = [expr]
+        elif expr not in columns:
+            columns = columns + [expr]
+
+        sql = self.compiler.compile_to_select(
+            columns=columns,
+            table=table,
+            where=where,
+            group_by=group_by,
+            having=having,
+            order_by=order_by,
+            limit=limit,
+        )
+
+        return self.execute(sql)
+
+
+def execute_sql(
+    sql: str,
+    connection: Any,
+    params: Optional[Dict[str, Any]] = None,
+) -> "pd.DataFrame":
+    """
+    便捷函数：执行 SQL
+
+    Args:
+        sql: SQL 字符串
+        connection: 数据库连接
+        params: 查询参数
+
+    Returns:
+        DataFrame 结果
+    """
+    executor = SQLExecutor(connection)
+    return executor.execute(sql, params)