Execution Plan (Explain)

The Execution Plan (Explain) feature in eKuiper Manager provides deep visibility into how the eKuiper engine interprets and executes your SQL rules. It transforms complex, low-level execution logic into actionable insights, helping developers optimize performance and troubleshoot processing bottlenecks.

Overview

When you write a stream processing rule, the eKuiper engine generates a logical and physical plan. In the eKuiper Manager, the Explain functionality allows you to:

• Visualize the Logic: See exactly how data moves from sources, through filters and aggregations, to sinks.
• Identify Bottlenecks: Spot expensive operations or inefficient windowing logic.
• AI-Enhanced Analysis: Leverage integrated AI models to translate technical execution JSON into plain-English optimizations.

Using the Execution Plan

To analyze a rule's execution plan within the UI:

1. Navigate to the Rules section and select a specific rule.
2. Click on the Execution Plan or Explain tab.
3. The interface will display the raw operator tree alongside an AI-generated breakdown of the processing steps.

Key Operators Explained

The plan typically consists of the following operators:

• Scan: The entry point where data is read from a stream or table.
• Filter (Where): The stage where data is dropped based on your conditions.
• Project (Select): Mapping and transforming specific fields.
• Window: How data is grouped in time (e.g., Tumble or Sliding windows).
• Aggregate: Math operations like AVG, SUM, or COUNT.
• Sink: The final delivery of the processed data.

AI-Powered Plan Analysis

eKuiper Manager goes beyond raw JSON by providing an AI Assistant specialized in SQL optimization. By sending the execution plan to an AI model (such as Gemini 1.5 Flash), the system generates a developer-friendly report.

API Endpoint: POST /api/ai/explain-plan

If you are extending the manager or using the API directly, you can trigger a plan explanation through the following interface:

Request Body: | Field | Type | Description | | :--- | :--- | :--- | | sql | string | The eKuiper SQL query being analyzed. | | plan | object | The raw JSON execution plan returned by the eKuiper server. | | modelName | string | (Optional) The OpenRouter model to use (defaults to google/gemini-flash-1.5). |

Example Usage:

curl -X POST /api/ai/explain-plan \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT temp, COUNT(*) FROM sensor_stream WHERE temp > 20 GROUP BY TumblingWindow(ss, 10)",
    "plan": { ...raw eKuiper plan... }
  }'

Output: The API returns a Markdown-formatted string containing:

• A step-by-step walkthrough of the logical operators.
• Detection of potential performance issues (e.g., high-cardinality grouping).
• Suggestions for SQL improvements.

Performance Hints

The Execution Plan is particularly useful for identifying the following common issues:

1. High Memory Usage

If the plan shows a large Window operator with a long duration or complex Aggregations, it indicates that the edge device may require more RAM to maintain the state before the window closes.

2. Excessive Filtering

If a Filter operator appears very late in the plan, it suggests that the engine is processing unnecessary data through early stages. Moving filter logic closer to the Scan (source) can improve throughput.

3. Sink Backpressure

By reviewing the plan in conjunction with Rule Metrics, you can see if the Sink operator is becoming a bottleneck, indicating that the destination (e.g., an MQTT broker or Database) cannot keep up with the processing speed.