## 概述

[LF Edge eKuiper](https://ekuiper.org/zh) 是 Golang 實現的輕量級物聯網邊緣分析、流式處理開源軟體，可以執行在各類資源受限的邊緣裝置上。eKuiper 的主要目標是在邊緣端提供一個流媒體軟體框架。其**規則引擎**允許使用者提供基於SQL 或基於圖形（類似於 Node-RED）的規則，在幾分鐘內建立物聯網邊緣分析應用。

本文中，我們將以原始碼為脈絡，闡述一條 SQL 從被 eKuiper 接收後，是如何從一條文字變成一個可執行的處理過程。透過本文，你可以瞭解到以下內容:

1. 一個 SQL 計算引擎基本的處理流程
2. eKuiper 在每個處理流程中的具體程式碼節點

## 準備

為了更加直觀地瞭解到 eKuiper 內部的程式碼執行邏輯，在講解 eKuiper 規則引擎的處理過程中，我們會涉及到 eKuiper 中的一部分程式碼，並對其中的關鍵部分進行較為詳細的講解。

為了更好地理解之後的內容，你需要了解:

1. eKuiper 專案：[https://github.com/lf-edge/ekuiper](https://github.com/lf-edge/ekuiper)
2. [Golang 的基礎用法](https://gobyexample.com/)

## 框架

從 eKuiper 接收到 SQL 的文字，到最終根據這個 SQL 的語義去做出相應的讀取與計算工作。eKuiper 內部的 SQL 計算引擎在其中承擔瞭解析、構造、最佳化與執行這總共 4 部分工作，即我們之後將重點關注 SQL 處理過程中的以下幾個環節:

1. SQL Parser 將 SQL 文字轉換為 AST 物件
2. 基於 AST 物件生成邏輯計劃
3. 最佳化邏輯計劃並生成執行運算元
4. 執行執行運算元，開始讀取資料與計算並最終將結果寫入到下游

## 從 SQL 文字到執行運算元樹

從這一節開始，我們將開始根據 eKuiper 中的程式碼節點，來理解一條 SQL 文字是如何一步步被最終轉換為一個可以被實際執行的運算元樹。

以下程式碼實際展示了 eKuiper 程式碼中解析文字、最佳化計劃、構造執行運算元這幾個處理流程，我們將一一進行展開瞭解。

```
func PlanSQLWithSourcesAndSinks(rule *api.Rule, sources []*node.SourceNode, sinks []*node.SinkNode) (*topo.Topo, error) {
    sql := rule.Sql
    conf.Log.Infof("Init rule with options %+v", rule.Options)
    stmt, err := xsql.GetStatementFromSql(sql)
    if err != nil {
       return nil, err
    }

......
    // Create logical plan and optimize. Logical plans are a linked list
    lp, err := createLogicalPlan(stmt, rule.Options, store)
    if err != nil {
       return nil, err
    }
    tp, err := createTopo(rule, lp, sources, sinks, streamsFromStmt)
    if err != nil {
       return nil, err
    }
    return tp, nil
}
```

### 解析 SQL 文字

透過以下函式，我們將一個 SQL 文字解析為了 AST 物件

```
func GetStatementFromSql(sql string) (*ast.SelectStatement, error) {
```

本文中我們暫時先不涉及 SQL 解析器中的具體實現細節，相關內容將在之後的 eKuiper 原始碼閱讀中進行講解。感興趣的朋友可以透過以下函式作為入口進行了解:

```
func (p *Parser) Parse() (*ast.SelectStatement, error) {
```

值得一提的是，在 SQL Parser的具體實現上，也有一些其他 well-known 的資料庫實現使用了 yacc 的方案來直接生成 SQL Parser。eKuiper 之所以選擇自己實現 SQL Parser，一個非常重要的原因是對於一個執行在邊緣端的應用而言，binary size 是一個非常重要的指標。自己實現 SQL Parser 而非使用 yacc 這類的 Parser Generator 的技術，有助於控制和降低 eKuiper 編譯後整體的 binary size 的大小。

### 構造與最佳化邏輯計劃

當 SQL 文字還解析為 AST 物件後，我們需要將該 AST 物件轉換為一個可以用來描述該 SQL 應當被計算引擎如何執行的邏輯計劃。這一步驟被封裝在了以下程式碼函式入口中:

```
func createLogicalPlan(stmt *ast.SelectStatement, opt *api.RuleOption, store kv.KeyValue) (LogicalPlan, error) {
```

在 createLogicalPlan 函式中，它接收一個 AST 樹物件，並返還一個邏輯計劃樹物件，在整個函式過程中，它總共做了以下 3 件事情:

1. 抽取 SQL 中的各類資訊，並將其與實際的表示式或者是 schema 資訊進行繫結。
2. 根據 AST 物件構造最初的邏輯計劃。
3. 根據最初的邏輯計劃進行邏輯最佳化。

在一條 SQL 中，它所帶的資訊裡包含了一些原本註冊計算引擎中的資訊，比如流、表的定義，也包含了一些臨時宣告的資訊，比如列或者表示式的 alias name。在以下程式碼函式入口中，eKuiper 會從 AST 樹物件中抽取出以下資訊，並進行響應的繫結:

```
func decorateStmt(s *ast.SelectStatement, store kv.KeyValue) ([]streamInfo, []*ast.Call, error) {
```

1. 從 AST 樹物件中抽取出流與表的 AST 物件，並從 eKuiper 的儲存中取出預先設定好的流、表的定義，並將這些 schema 資訊繫結到 ast 物件中。
2. 從 AST 物件中將查詢中的 filed 與各個流、表進行繫結

當我們處理好 AST 樹物件中的各個節點的資訊繫結後，我們就可以根據 AST 樹物件來構造一個最初的邏輯計劃。以下程式碼顯示了在 eKuiper 中是如何根據自底向上的構建邏輯計劃。從底層的 DataSource 運算元，一路向上 build 邏輯運算元，直至整個邏輯運算元樹構造完畢。

```
func createLogicalPlan(stmt *ast.SelectStatement, opt *api.RuleOption, store kv.KeyValue) (LogicalPlan, error) {
// 1. build Datasource
// 2. build Window
// 3. Buld JoinAlign / Join
// 4. Build Filter
// 5. Build Agg
// 6. Build Having
// 7. Build Sort
// 8. Build Proj
}
```

當我們獲得了最原始的邏輯計劃樹以後，我們需要對邏輯計劃進行邏輯最佳化。邏輯最佳化階段會對原本的計劃進行最佳化。邏輯最佳化階段，簡單來說就是對一個邏輯運算元樹進行等價的變換，這個變換並不會影響最終的計算結果，但是可以讓計算過程減少更多不必要的計算量。

舉一個簡單的例子，對於 `select * from t1 join t2 on [t1.](http://t1.id)a = t2.a where t1.b > 10` 這條 SQL 來說，其原本的邏輯計劃如下:

![原本的邏輯計劃](https://assets.emqx.com/images/4b77f7a75bf1c828ce8ebf7f0c18e069.png)

然後在邏輯最佳化階段，我們可以將 Filter 運算元進行下推至 Join 運算元之下，從而讓參與 Join 運算元的資料量被提前過濾一部分，來減少整個計算過程中所涉及到的計算量。

![最佳化後的邏輯](https://assets.emqx.com/images/3fe75bdd69edf4720de6f7df5ab72082.png)

以下程式碼展示了 eKuiper 中是如何進行邏輯最佳化的：

```
var optRuleList = []logicalOptRule{
    &columnPruner{},
    &predicatePushDown{},
}

func optimize(p LogicalPlan) (LogicalPlan, error) {
    var err error
    for _, rule := range optRuleList {
        p, err = rule.optimize(p)
        if err != nil {
            return nil, err
        }
    }
    return p, err
}
```

在隨後的系列當中我們會比較詳細地介紹目前 eKuiper 中的邏輯最佳化環節中的程式碼細節。

當我們的邏輯計劃最佳化完畢以後，我們需要根據邏輯計劃來構造具體的執行運算元。在 eKuiper 中，我們透過 Topo 結構來維護整個執行運算元的上下文環境。

以下程式碼展示了構建執行運算元的函式入口：

```
func createTopo(rule *api.Rule, lp LogicalPlan, sources []*node.SourceNode, sinks []*node.SinkNode, streamsFromStmt []string) (*topo.Topo, error) {
type Topo struct {
   ......
   sources            []node.DataSourceNode
   sinks              []*node.SinkNode
   ops                []node.OperatorNode
   ......
}
```

Topo 作為執行運算元 Context，會將邏輯計劃中的 DataSource 運算元放在 sources 中，將其他運算元放在 ops 中，而最終的 SQL 結果會彙總到 sinks 中。 在這裡我們重點關注運算元是如何構造的:

以下程式碼展示了 eKuiper 中是如何根據邏輯運算元構造執行運算元的：

```
func buildOps(lp LogicalPlan, tp *topo.Topo, options *api.RuleOption, sources []*node.SourceNode, streamsFromStmt []string, index int) (api.Emitter, int, error) {
    var inputs []api.Emitter
    newIndex := index
    for _, c := range lp.Children() {
       input, ni, err := buildOps(c, tp, options, sources, streamsFromStmt, newIndex)
       .......
    }
    ......
    switch t := lp.(type) {
    case *DataSourcePlan:
       isSchemaless := t.isSchemaless
       switch t.streamStmt.StreamType {
       case ast.TypeStream:
          ......
          op = srcNode
    ......
    case *ProjectPlan:
       op = Transform(&operator.ProjectOp{ColNames: t.colNames, AliasNames: t.aliasNames, AliasFields: t.aliasFields, ExprFields: t.exprFields, IsAggregate: t.isAggregate, AllWildcard: t.allWildcard, WildcardEmitters: t.wildcardEmitters, ExprNames: t.exprNames, SendMeta: t.sendMeta}, fmt.Sprintf("%d_project", newIndex), options)
    default:
       return nil, 0, fmt.Errorf("unknown logical plan %v", t)
    }
    ......
    if onode, ok := op.(node.OperatorNode); ok {
       tp.AddOperator(inputs, onode)
    }
    return op, newIndex, nil
}
```

在構造運算元的過程中，我們主要關注 2 個問題:

1. buildOps 是如何遍歷整個邏輯運算元樹，將每個邏輯運算元轉換為執行運算元
2. buildOps 是如何串聯起整個執行運算元的樹形結構，將下層運算元的 Ouput 結果傳遞給上層運算元的 Input 來源。

在 buildOps 過程中，透過遞迴的方式，以自底向上的方式遍歷整個邏輯運算元樹來構造執行運算元。當下層運算元構造完畢以後，我們在以下程式碼中會將下層運算元的 Ouput 作為結果引數傳遞給上層運算元的構造過程中，將下層運算元的 Output 和上層運算元的 Input 連線起來

```
if onode, ok := op.(node.OperatorNode); ok {
   tp.AddOperator(inputs, onode)
}
```

當執行運算元樹被建立完畢以後，我們會將頂層運算元的 Output 和這條 SQL 的 sink 連線起來，從而使得 eKuiper 會將 SQL 計算的結果寫入到下游的 sink 中。

```
func createTopo(rule *api.Rule, lp LogicalPlan, sources []*node.SourceNode, sinks []*node.SinkNode, streamsFromStmt []string) (*topo.Topo, error) {
    ......
    input, _, err := buildOps(lp, tp, rule.Options, sources, streamsFromStmt, 0)
    if err != nil {
        return nil, err
    }
    inputs := []api.Emitter{input}
    ......
    for _, sink := range sinks {
        tp.AddSink(inputs, sink)
    }
    ......
    return tp, nil
}
```

## 啟動執行運算元樹

當執行運算元樹被構造完畢後，我們就需要啟動執行運算元樹來真正執行這條 SQL，在以下的程式碼中展示了 eKuiper 啟動執行運算元的程式碼入口:

```
func (s *Topo) Open()  版權宣告： 本文為 EMQ 原創，轉載請註明出處。
> 
> 原文連結：[https://www.emqx.com/zh/blog/ekuiper-source-code-interpretation](https://www.emqx.com/zh/blog/ekuiper-source-code-interpretation)

eKuiper 原始碼解讀：從一條 SQL 到流處理任務的旅程

相關文章