Add explain plan support

Author: Peng Ren

README.md

@@ -92,6 +92,7 @@ pip install -e .
   - [UPDATE Statements](#update-statements)
   - [DELETE Statements](#delete-statements)
   - [View Management](#view-management)
+  - [Explain Statement](#explain-statement)
   - [Transaction Support](#transaction-support)
 - [SQL to MongoDB Mapping](#sql-to-mongodb-mapping)
 - [Apache Superset Integration](#apache-superset-integration)
@@ -542,6 +543,38 @@ cursor.execute("DROP VIEW active_users")
 
 **Note:** The pipeline must be a valid JSON array string enclosed in single quotes. `CREATE VIEW` maps to `db.command({"create": view_name, "viewOn": collection, "pipeline": [...]})` and `DROP VIEW` maps to `db.command({"drop": view_name})`.
 
+### Explain Statement
+
+Prefix any `SELECT` statement with `EXPLAIN` to inspect the MongoDB [query plan](https://www.mongodb.com/docs/compass/query-plan/). PyMongoSQL wraps the inner command with MongoDB's [`explain`](https://www.mongodb.com/docs/manual/reference/command/explain/) command and flattens the winning plan tree into a two-column result set (`stage`, `details`) that renders well in table views (e.g. Apache Superset, DB clients).
+
+```python
+# Default verbosity: queryPlanner
+cursor.execute("EXPLAIN SELECT * FROM users WHERE age > 21")
+for stage, details in cursor.fetchall():
+    print(stage, details)
+
+# Request executionStats (actual timing, docs/keys examined) or allPlansExecution
+cursor.execute("EXPLAIN (verbosity executionStats) SELECT * FROM users WHERE age > 21")
+```
+
+**Supported verbosities** (grammar-native options, unquoted identifiers):
+
+| Verbosity | What you get |
+|---|---|
+| `queryPlanner` _(default)_ | Winning plan, rejected plans, namespace, parsedQuery |
+| `executionStats` | `queryPlanner` output + execution time, documents returned/examined, index keys examined |
+| `allPlansExecution` | `executionStats` for the winning plan **and** each rejected candidate plan |
+
+Example output rows (`queryPlanner`):
+
+```
+stage                  details
+namespace              mydb.users
+parsedQuery            {"age": {"$gt": 21}}
+├─ COLLSCAN            {"direction": "forward", "filter": {...}}
+rejectedPlans          []
+```
+
 ### Transaction Support
 
 PyMongoSQL supports DB API 2.0 transactions for ACID-compliant database operations. Use the `begin()`, `commit()`, and `rollback()` methods to manage transactions:
@@ -588,6 +621,7 @@ The table below shows how PyMongoSQL translates SQL operations into MongoDB comm
 | `DELETE FROM col WHERE ...` | `{delete: col, deletes: [{q: filter, limit: 0}]}` | `db.command("delete", ...)` |
 | `CREATE VIEW v ON col AS '[...]'` | `{create: v, viewOn: col, pipeline: [...]}` | `db.command("create", ...)` |
 | `DROP VIEW v` | `{drop: v}` | `db.command("drop", ...)` |
+| `EXPLAIN <select>` | `{explain: <find\|aggregate cmd>, verbosity: "queryPlanner"}` | `db.command("explain", ...)` |
 
 ### SQL Clauses to MongoDB Query Components
 

pymongosql/executor.py

@@ -11,6 +11,7 @@
 from .helper import SQLHelper
 from .retry import execute_with_retry
 from .sql.delete_builder import DeleteExecutionPlan
+from .sql.explain_builder import ExplainExecutionPlan
 from .sql.insert_builder import InsertExecutionPlan
 from .sql.parser import SQLParser
 from .sql.query_builder import QueryExecutionPlan
@@ -758,10 +759,93 @@ def execute(
         return self._execute_execution_plan(self._execution_plan, connection, parameters)
 
 
+class ExplainExecution(ExecutionStrategy):
+    """Execution strategy for ``EXPLAIN [ (opt val, ...) ] <statement>`` wrappers.
+
+    Parses via :class:`SQLParser` (grammar-native EXPLAIN production) to obtain
+    an :class:`ExplainExecutionPlan`, delegates command construction and result
+    flattening to the plan, and runs the resulting ``explain`` command through
+    the shared connection/retry path.
+    """
+
+    _EXPLAIN_PATTERN = re.compile(r"^\s*EXPLAIN\b", re.IGNORECASE)
+
+    @property
+    def execution_plan(self) -> QueryExecutionPlan:
+        return self._execution_plan
+
+    def supports(self, context: ExecutionContext) -> bool:
+        return bool(self._EXPLAIN_PATTERN.match(context.query))
+
+    def _parse_sql(self, sql: str) -> ExplainExecutionPlan:
+        try:
+            parser = SQLParser(sql)
+            plan = parser.get_execution_plan()
+            if not isinstance(plan, ExplainExecutionPlan):
+                raise SqlSyntaxError("Expected EXPLAIN execution plan")
+            if not plan.validate():
+                raise SqlSyntaxError("Generated EXPLAIN plan is invalid")
+            return plan
+        except SqlSyntaxError:
+            raise
+        except Exception as e:
+            _logger.error(f"SQL parsing failed: {e}")
+            raise SqlSyntaxError(f"Failed to parse SQL: {e}")
+
+    def execute(
+        self,
+        context: ExecutionContext,
+        connection: Any,
+        parameters: Optional[Union[Sequence[Any], Dict[str, Any]]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        _logger.debug(f"Using explain execution for query: {context.query[:100]}")
+
+        # Normalize named parameters to positional, matching StandardQueryExecution.
+        processed_query = context.query
+        processed_params = parameters
+        if isinstance(parameters, dict):
+            param_names = re.findall(r":(\w+)", context.query)
+            processed_params = [parameters[name] for name in param_names]
+            processed_query = re.sub(r":(\w+)", "?", context.query)
+
+        explain_plan = self._parse_sql(processed_query)
+        # Store the synthesized result plan (QueryExecutionPlan) so the cursor
+        # can wire it directly into the ResultSet for column description.
+        self._execution_plan = explain_plan.result_plan
+
+        # Build the explain command (validates inner plan is a supported SELECT).
+        explain_cmd = explain_plan.build_command(processed_params)
+
+        if not connection:
+            raise OperationalError("No connection provided")
+
+        _logger.debug(f"Executing MongoDB explain command: {explain_cmd}")
+
+        try:
+            explain_result = _run_db_command(connection.database, explain_cmd, connection, "explain command")
+        except PyMongoError as e:
+            _logger.error(f"MongoDB explain execution failed: {e}")
+            raise DatabaseError(f"Explain execution failed: {e}")
+
+        # Return flattened rows as a command result. The cursor handles
+        # ExplainExecutionPlan -> result_plan translation when wiring the ResultSet.
+        return {
+            "cursor": {"id": 0, "firstBatch": explain_plan.flatten_result(explain_result)},
+            "ok": 1,
+        }
+
+
 class ExecutionPlanFactory:
     """Factory for creating appropriate execution strategy based on query context"""
 
-    _strategies = [ViewExecution(), StandardQueryExecution(), InsertExecution(), UpdateExecution(), DeleteExecution()]
+    _strategies = [
+        ExplainExecution(),
+        ViewExecution(),
+        StandardQueryExecution(),
+        InsertExecution(),
+        UpdateExecution(),
+        DeleteExecution(),
+    ]
 
     @classmethod
     def get_strategy(cls, context: ExecutionContext) -> ExecutionStrategy:

pymongosql/sql/ast.py

@@ -38,6 +38,9 @@ def __init__(self) -> None:
         self._update_parse_result = UpdateParseResult.for_visitor()
         # Track current statement kind generically so UPDATE/DELETE can reuse this
         self._current_operation: str = "select"  # expected values: select | insert | update | delete
+        # EXPLAIN wrapper state (grammar: root : EXPLAIN? (options)? statement EOF)
+        self._is_explain: bool = False
+        self._explain_options: Dict[str, str] = {}
         self._handlers = self._initialize_handlers()
 
     def _initialize_handlers(self) -> Dict[str, BaseHandler]:
@@ -69,11 +72,47 @@ def current_operation(self) -> str:
         """Get the current operation type (select, insert, delete, or update)"""
         return self._current_operation
 
+    @property
+    def is_explain(self) -> bool:
+        """Whether the parsed statement was wrapped in EXPLAIN."""
+        return self._is_explain
+
+    @property
+    def explain_options(self) -> Dict[str, str]:
+        """Options collected from ``EXPLAIN (key value, ...)`` clause."""
+        return dict(self._explain_options)
+
     def visitRoot(self, ctx: PartiQLParser.RootContext) -> Any:
         """Visit root node and process child nodes"""
         _logger.debug("Starting to parse SQL query")
         # Reset to default SELECT operation at the start of each query
         self._current_operation = "select"
+        self._is_explain = False
+        self._explain_options = {}
+
+        # Detect EXPLAIN wrapper per grammar:
+        #   root : (EXPLAIN (PAREN_LEFT explainOption (COMMA explainOption)* PAREN_RIGHT)? )? statement EOF;
+        try:
+            explain_token = ctx.EXPLAIN() if hasattr(ctx, "EXPLAIN") else None
+        except Exception:
+            explain_token = None
+
+        if explain_token is not None:
+            self._is_explain = True
+            try:
+                option_ctxs = ctx.explainOption() or []
+            except Exception:
+                option_ctxs = []
+            for opt in option_ctxs:
+                try:
+                    param_tok = getattr(opt, "param", None)
+                    value_tok = getattr(opt, "value", None)
+                    if param_tok is not None and value_tok is not None:
+                        self._explain_options[param_tok.text] = value_tok.text
+                except Exception as e:
+                    _logger.warning(f"Error parsing explainOption: {e}")
+            _logger.debug(f"EXPLAIN detected with options: {self._explain_options}")
+
         try:
             result = self.visitChildren(ctx)
             return result