feat: engine support EXPLAIN/PROFILE (#708)

## Summary
Implement PROFILE and EXPLAIN execution modes for NeuG with ASCII tree
formatted output.

## Changes Made

### Core Implementation (C++)
- **query_result.h/cc**: Added `profile_result_text()` and
`has_profile_result()` methods for formatted output
- **response.proto**: Added ProfileResult message containing operator
metrics (elapsed_ms, output_rows, operator tree)
- **query_processor.cc**: Three-way execution branching for NONE,
PROFILE, and EXPLAIN modes

### Python Interface
- **py_query_result.h/cc**: pybind11 bindings for Python access
- **query_result.py**: High-level Pythonic wrapper with English
docstrings
  - `has_profile_result()` → bool
  - `get_profile_text()` → formatted ASCII tree string
  - `get_profile_metrics()` → dict with operator tree structure

### Testing & Examples
- **test_explain_profile.cpp**: 9 test cases covering single scan,
joins, aggregations, EXPLAIN mode
- **explain_profile_example.py**: End-to-end example demonstrating all
three modes

## Example Usage

### PROFILE mode (execute + collect metrics)
```
neug > PROFILE MATCH (n:person) RETURN n.name;

+-------------+
| _0_n.name   |
+=============+
| marko       |
+-------------+
| vadas       |
+-------------+
| josh        |
+-------------+
| peter       |
+-------------+



╔════════════════════════════════════════╗
║         PROFILE REPORT                 ║
╚════════════════════════════════════════╝
Total output tuples: 4
Total elapsed time: 0.000 s

┌───────────────────────────────────────┐
│           ScanWithGPredOpr            │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     4 tuples   │
└───────────────────────────────────────┘
┌───────────────────────────────────────┐
│              ProjectOpr               │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     4 tuples   │
└───────────────────────────────────────┘
┌───────────────────────────────────────┐
│                SinkOpr                │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     4 tuples   │
└───────────────────────────────────────┘
```

### EXPLAIN mode (no execution, empty metrics)
```
neug > EXPLAIN MATCH (n:person) RETURN n.name;

No results (total records: 0)

╔════════════════════════════════════════╗
║         PROFILE REPORT                 ║
╚════════════════════════════════════════╝
Total output tuples: 0
Total elapsed time: 0.000 s

┌───────────────────────────────────────┐
│           ScanWithGPredOpr            │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     0 tuples   │
└───────────────────────────────────────┘
┌───────────────────────────────────────┐
│              ProjectOpr               │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     0 tuples   │
└───────────────────────────────────────┘
┌───────────────────────────────────────┐
│                SinkOpr                │
├───────────────────────────────────────┤
│   time: 0.000s | rows:     0 tuples   │
└───────────────────────────────────────┘
```

---------

Co-authored-by: mazhuojohn <mazhuojohn@U-T4RYCVM3-2051.local>

Author: johnmzz

doc/source/development/performance_debugging.md

@@ -37,6 +37,10 @@ class IOperator {
   virtual neug::result<Context> Eval(IStorageInterface& graph,
                                      const ParamsMap& params, Context&& ctx,
                                      OprTimer* timer) = 0;
+
+  virtual void build_explain_children(OprTimer* parent_timer,
+                                      const ParamsMap& params,
+                                      IStorageInterface& graph) {}
 };
 
 using OpBuildResultT = std::pair<std::unique_ptr<IOperator>, ContextMeta>;

include/neug/execution/execute/operator.h

@@ -34,6 +34,9 @@ class Pipeline {
   neug::result<Context> Execute(IStorageInterface& graph, Context&& ctx,
                                 const ParamsMap& params, OprTimer* timer);
 
+  neug::result<std::unique_ptr<OprTimer>> explain_tree(IStorageInterface& graph,
+                                                       const ParamsMap& params);
+
  private:
   std::vector<std::unique_ptr<IOperator>> operators_;
 };

include/neug/execution/execute/pipeline.h

@@ -30,14 +30,17 @@ struct CacheValue {
   ParamsMetaMap params_type;
   neug::MetaDatas result_schema;
   physical::ExecutionFlag flags;
+  physical::ExplainMode explain_mode = physical::ExplainMode::NONE;
 
   CacheValue(Pipeline pipeline, ParamsMetaMap params_type,
              const neug::MetaDatas& result_schema,
-             physical::ExecutionFlag flags)
+             physical::ExecutionFlag flags,
+             physical::ExplainMode explain_mode = physical::ExplainMode::NONE)
       : pipeline(std::move(pipeline)),
         params_type(std::move(params_type)),
         result_schema(result_schema),
-        flags(flags) {}
+        flags(flags),
+        explain_mode(explain_mode) {}
 };
 
 /**
@@ -83,16 +86,17 @@ class GlobalQueryCache {
 
     auto params_type =
         execution::PlanParser::parse_params_type(plan_result.first);
+    auto explain_mode = plan_result.first.explain_mode();
     {
       std::unique_lock<std::shared_mutex> write_lock(mutex_);
       auto iter = cache_.find(query);
       if (iter != cache_.end()) {
         return iter->second;
       }
-      cache_.emplace(query,
-                     std::make_shared<CacheValue>(std::move(pipeline_result),
-                                                  std::move(params_type), sch,
-                                                  plan_result.first.flag()));
+      cache_.emplace(
+          query, std::make_shared<CacheValue>(
+                     std::move(pipeline_result), std::move(params_type), sch,
+                     plan_result.first.flag(), explain_mode));
       return cache_.at(query);
     }
   }

include/neug/execution/execute/query_cache.h

@@ -15,12 +15,15 @@
 #pragma once
 
 #include <chrono>
+#include <functional>
 #include <iostream>
 #include <memory>
 #include <string>
 #include <utility>
 #include <vector>
 
+#include "neug/generated/proto/response/response.pb.h"
+
 namespace neug {
 
 namespace execution {
@@ -84,6 +87,9 @@ class OprTimer {
 
   OprTimer& operator+=(const OprTimer& other);
 
+  // Convert OprTimer tree to ProfileResult protobuf message
+  static ProfileResult ToProfileResult(OprTimer* root);
+
   double elapsed() const {
     double time = time_;
     auto next = next_.get();
@@ -95,6 +101,17 @@ class OprTimer {
   }
 
  private:
+  size_t get_children_count() const { return children_.size(); }
+
+  OprTimer* get_child(size_t index) const {
+    if (index < children_.size()) {
+      return children_[index].get();
+    }
+    return nullptr;
+  }
+
+  uint64_t get_num_tuples() const { return numTuples_; }
+
   std::vector<std::unique_ptr<OprTimer>> children_;
   std::unique_ptr<OprTimer> next_;
   std::string name_;

include/neug/execution/utils/opr_timer.h

@@ -81,6 +81,13 @@ class QueryProcessor {
       AccessMode access_mode, const execution::ParamsMap& parameters = {},
       int32_t num_threads = 0);
 
+  result<QueryResult> execute_explain_mode(
+      const std::string& query_string,
+      std::shared_ptr<execution::CacheValue> cache_value,
+      const execution::ParamsMap& parameters, IStorageInterface& graph,
+      AccessMode access_mode, const PropertyGraph& pg,
+      google::protobuf::Arena& arena);
+
   bool need_exclusive_lock(AccessMode access_mode);
 
   void update_compiler_meta_if_needed(const PropertyGraph& pg,

include/neug/main/query_processor.h

@@ -178,6 +178,19 @@ class QueryResult {
    */
   std::string Serialize() const;
 
+  /**
+   * @brief Check if profile result is available.
+   */
+  bool has_profile_result() const;
+
+  /**
+   * @brief Get human-readable PROFILE/EXPLAIN text output.
+   *
+   * Returns empty string if no profile_result available.
+   * Suitable for CLI output and debugging.
+   */
+  std::string profile_result_text() const;
+
  private:
   void ValidateCursorAccess(size_t column_index) const;
   size_t GetColumnIndex(const std::string& column_name) const;

include/neug/main/query_result.h

@@ -135,9 +135,25 @@ message Array {
   }
 }
 
+message ProfileResult {
+  message OperatorMetrics {
+    int64 operator_id = 1;
+    int64 parent_id = 2;
+    string operator_name = 3;
+    double elapsed_ms = 4;
+    uint64 output_rows = 5;
+    repeated int64 child_ids = 6;
+  }
+
+  double total_elapsed_ms = 1;
+  uint64 total_output_rows = 2;
+  repeated OperatorMetrics operators = 3;
+}
+
 message QueryResponse {
   int32 row_count = 1;
   MetaDatas schema = 2;
   repeated Array arrays = 3;
+  ProfileResult profile_result = 4;
 };
 

proto/response.proto

@@ -85,6 +85,21 @@ class JoinOpr : public IOperator {
     return out;
   }
 
+  void build_explain_children(OprTimer* parent_timer, const ParamsMap& params,
+                              IStorageInterface& graph) override {
+    // Build explain tree for left and right pipelines
+    // and add them as children to the parent timer
+    auto left_tree_result = left_pipeline_.explain_tree(graph, params);
+    auto right_tree_result = right_pipeline_.explain_tree(graph, params);
+
+    if (left_tree_result && left_tree_result.value()) {
+      parent_timer->add_child(std::move(left_tree_result.value()));
+    }
+    if (right_tree_result && right_tree_result.value()) {
+      parent_timer->add_child(std::move(right_tree_result.value()));
+    }
+  }
+
  private:
   neug::execution::Pipeline left_pipeline_;
   neug::execution::Pipeline right_pipeline_;

src/execution/execute/ops/retrieve/join.cc

@@ -65,6 +65,18 @@ class UnionOpr : public IOperator {
     return out;
   }
 
+  void build_explain_children(OprTimer* parent_timer, const ParamsMap& params,
+                              IStorageInterface& graph) override {
+    // Build explain tree for each sub plan
+    // and add them as children to the parent timer
+    for (auto& plan : sub_plans_) {
+      auto tree_result = plan.explain_tree(graph, params);
+      if (tree_result && tree_result.value()) {
+        parent_timer->add_child(std::move(tree_result.value()));
+      }
+    }
+  }
+
  private:
   std::vector<Pipeline> sub_plans_;
 };