![Nebula Graph 原始碼解讀系列 ｜ Vol.02 詳解 Validator](https://www-cdn.nebula-graph.com.cn/nebula-blog/nebula-graph-source-code-reading-02.png)

## 整體架構

Nebula Graph Query Engine 主要分為四個模組，分別是 Parser、Validator、Optimizer 和 Executor。

![](https://www-cdn.nebula-graph.com.cn/nebula-blog/code-reading-validator.png)

Parser 完成對語句的詞法語法解析並生成抽象語法樹（AST），Validator 會將 AST 轉化為執行計劃，Optimizer 對執行計劃進行最佳化，而 Executor 負責實際資料的計算。

這篇文章我們主要介紹 Validator 的實現原理。

## 目錄結構

Validator 程式碼實現在 `src/validator` 和 `src/planner` 目錄。

`src/validator` 目錄主要包括各種子句的 Validator 實現，比如 `OrderByValidator`、`LimitValidator`、`GoValidator` 等等。

``` 
validator/
├── ACLValidator.h
├── AdminJobValidator.h
├── AdminValidator.h
├── AssignmentValidator.h
├── BalanceValidator.h
├── DownloadValidator.h
├── ExplainValidator.h
├── FetchEdgesValidator.h
├── FetchVerticesValidator.h
├── FindPathValidator.h
├── GetSubgraphValidator.h
├── GoValidator.h
├── GroupByValidator.h
├── IngestValidator.h
├── LimitValidator.h
├── LookupValidator.h
├── MaintainValidator.h
├── MatchValidator.h
├── MutateValidator.h
├── OrderByValidator.h
├── PipeValidator.h
├── ReportError.h
├── SequentialValidator.h
├── SetValidator.h
├── TraversalValidator.h
├── UseValidator.h
├── Validator.h
└── YieldValidator.h 
```

src/planner/plan 目錄**定義了所有 PlanNode 的資料結構，用於生成最終的執行計劃**。比如，當查詢語句中含有聚合函式時，執行計劃中會生成 Aggregate 節點，Aggregate 類會指定聚合函式計算時所需的全部資訊，包括分組列和聚合函式表示式，Aggregate 類定義在 Query.h 中。Nebula 定義了一百多種 PlanNode，`PlanNode::kind` 定義在 PlanNode.h 中，在此不做詳細闡述。

``` 
planner/plan/
├── Admin.cpp          
├── Admin.h             // administration related  nodes
├── Algo.cpp
├── Algo.h              // graph algorithm related nodes
├── ExecutionPlan.cpp
├── ExecutionPlan.h     // explain and profile nodes
├── Logic.cpp
├── Logic.h             // nodes introduced by the implementation layer
├── Maintain.cpp
├── Maintain.h          // schema related nodes
├── Mutate.cpp
├── Mutate.h            // DML related nodes
├── PlanNode.cpp
├── PlanNode.h          // plan node base classes
├── Query.cpp
├── Query.h             // DQL related nodes
└── Scan.h              // index related nodes
 ```

src/planner 目錄還定義了 nGQL 和 match 語句的 planner 實現，用於生成 nGQL 和 match 語句執行計劃。

## 原始碼解析

validator 入口函式是 `Validator::validate(Sentence*, QueryContext*)`，負責將 parser 生成的抽象語法樹轉化為執行計劃，QueryContext 中會儲存最終生成的執行計劃 root 節點，函式程式碼如下：

```cpp 
Status Validator::validate(Sentence* sentence, QueryContext* qctx) {
    DCHECK(sentence != nullptr);
    DCHECK(qctx != nullptr);

// Check if space chosen from session. if chosen, add it to context.
    auto session = qctx->rctx()->session();
    if (session->space().id > kInvalidSpaceID) {
        auto spaceInfo = session->space();
        qctx->vctx()->switchToSpace(std::move(spaceInfo));
    }

auto validator = makeValidator(sentence, qctx);
    NG_RETURN_IF_ERROR(validator->validate());

auto root = validator->root();
    if (!root) {
        return Status::SemanticError("Get null plan from sequential validator");
    }
    qctx->plan()->setRoot(root);
    return Status::OK();
} 
```

該函式首先獲取當前 session 的 space 資訊並儲存在 ValidateContext中，之後呼叫 `Validator::makeValidator()` 和 `Validator::validate()` 函式。
 
`Validator::makeValidator()` 的功能是生成子句的 validator，該函式會首先生成 SequentialValidator，SequentialValidator 是 validator 的入口，所有語句都會首先生成 SequentialValidator。

`SequentialValidator::validateImpl()` 函式會呼叫 `Validator::makeValidator()` 生成相應子句的 validator。函式程式碼如下：

```cpp
Status SequentialValidator::validateImpl() {
    Status status;
    if (sentence_->kind() != Sentence::Kind::kSequential) {
        return Status::SemanticError(
                "Sequential validator validates a SequentialSentences, but %ld is given.",
                static_cast<int64_t>(sentence_->kind()));
    }
    auto seqSentence = static_cast<sequentialsentences>(sentence_);
    auto sentences = seqSentence->sentences();

seqAstCtx_->startNode = StartNode::make(seqAstCtx_->qctx);
    for (auto* sentence : sentences) {
        auto validator = makeValidator(sentence, qctx_);
        NG_RETURN_IF_ERROR(validator->validate());
        seqAstCtx_->validators.emplace_back(std::move(validator));
    }

return Status::OK();
}
 ```

同樣地，PipeValidator、AssignmentValidator 和 SetValidator 也會生成相應子句的 validator。

`Validator::validate()` 負責生成執行計劃，函式程式碼如下：

```cpp
Status Validator::validate() {
    auto vidType = space_.spaceDesc.vid_type_ref().value().type_ref().value();
    vidType_ = SchemaUtil::propTypeToValueType(vidType);

NG_RETURN_IF_ERROR(validateImpl());

// Check for duplicate reference column names in pipe or var statement
    NG_RETURN_IF_ERROR(checkDuplicateColName());

// Execute after validateImpl because need field from it
    if (FLAGS_enable_authorize) {
        NG_RETURN_IF_ERROR(checkPermission());
    }

NG_RETURN_IF_ERROR(toPlan());

return Status::OK();
}
```

該函式首先檢查 space 和使用者許可權等資訊，之後呼叫函式 `Validator:validateImpl()` 完成子句校驗，`validateImpl()` 函式是 Validator 類的純虛擬函式，利用多型呼叫不同子句的 `validatorImpl()` 實現函式。最後呼叫 `Validator::toPlan()` 函式生成執行計劃，`toPlan()` 函式會生成子句的執行計劃，子執行計劃會被連線形成完整的執行計劃，比如 match 語句中透過函式 `MatchPlanner::connectSegments()` 連線子執行計劃，而 nGQL 語句則透過 `Validator::appendPlan()` 實現。

## 舉例

下面我們以 nGQL 語句為例具體介紹一下以上流程。

語句：

```
GO 3 STEPS FROM "vid" OVER edge 
WHERE $$.tag.prop > 30 
YIELD edge._dst AS dst 
| ORDER BY $-.dst
```
這條 nGQL 語句在 validator 階段主要經歷三個過程：

### 製作子句 validator

首先會呼叫 `Validator::makeValidator()` 生成 SequentialValidator。在 `SequentialValidator::validateImpl()` 函式中會生成 PipeValidator，PipeValidator 會製作左右子句的 validator，分別是 GoValidator 和 OrderByValidator。
 
### 子句校驗

子句校驗階段會分別校驗 Go 和 OrderBy 子句。

以 Go 語句為例，會先校驗語義錯誤，比如 aggregate 函式使用不當、表示式型別不匹配等等，然後依次校驗內部子句，校驗過程中會把校驗的中間結果儲存在 GoContext 中，作為 GoPlanner 生成執行計劃的依據。比如 validateWhere() 會儲存過濾條件表示式用於之後生成 Filter 執行計劃節點。

```cpp
    NG_RETURN_IF_ERROR(validateStep(goSentence->stepClause(), goCtx_->steps));  // 校驗 step 子句
    NG_RETURN_IF_ERROR(validateStarts(goSentence->fromClause(), goCtx_->from)); // 校驗 from 子句
    NG_RETURN_IF_ERROR(validateOver(goSentence->overClause(), goCtx_->over));   // 校驗 over 子句
    NG_RETURN_IF_ERROR(validateWhere(goSentence->whereClause()));               // 校驗 where 子句
    NG_RETURN_IF_ERROR(validateYield(goSentence->yieldClause()));               // 校驗 yield 子句
```

### plan 生成
  
Go 語句的子執行計劃由 GoPlanner::transform(Astcontext*) 函式生成，程式碼如下：

```cpp
StatusOr<subplan> GoPlanner::transform(AstContext* astCtx) {
    goCtx_ = static_cast<gocontext>(astCtx);
    auto qctx = goCtx_->qctx;
    goCtx_->joinInput = goCtx_->from.fromType != FromType::kInstantExpr;
    goCtx_->joinDst = !goCtx_->exprProps.dstTagProps().empty();

SubPlan startPlan = QueryUtil::buildStart(qctx, goCtx_->from, goCtx_->vidsVar);

auto& steps = goCtx_->steps;
    if (steps.isMToN()) {
        return mToNStepsPlan(startPlan);
    }

if (steps.steps() == 0) {
        auto* pt = PassThroughNode::make(qctx, nullptr);
        pt->setColNames(std::move(goCtx_->colNames));
        SubPlan subPlan;
        subPlan.root = subPlan.tail = pt;
        return subPlan;
    }

if (steps.steps() == 1) {
        return oneStepPlan(startPlan);
    }
    return nStepsPlan(startPlan);
}
```

該函式首先呼叫 QueryUtil::buildStart() 構造start 節點，然後根據四種不同 step 的情況採用不同的方式生成計劃。本例中語句會採用 nStepPlan 策略。

GoPlanner::nStepsPlan() 函式程式碼如下：

```cpp
SubPlan GoPlanner::nStepsPlan(SubPlan& startVidPlan) {
    auto qctx = goCtx_->qctx;

auto* start = StartNode::make(qctx);
    auto* gn = GetNeighbors::make(qctx, start, goCtx_->space.id);
    gn->setSrc(goCtx_->from.src);
    gn->setEdgeProps(buildEdgeProps(true));
    gn->setInputVar(goCtx_->vidsVar);

auto* getDst = QueryUtil::extractDstFromGN(qctx, gn, goCtx_->vidsVar);

PlanNode* loopBody = getDst;
    PlanNode* loopDep = nullptr;
    if (goCtx_->joinInput) {
        auto* joinLeft = extractVidFromRuntimeInput(startVidPlan.root);
        auto* joinRight = extractSrcDstFromGN(getDst, gn->outputVar());
        loopBody = trackStartVid(joinLeft, joinRight);
        loopDep = joinLeft;
    }

auto* condition = loopCondition(goCtx_->steps.steps() - 1, gn->outputVar());
    auto* loop = Loop::make(qctx, loopDep, loopBody, condition);

auto* root = lastStep(loop, loopBody == getDst ? nullptr : loopBody);
    SubPlan subPlan;
    subPlan.root = root;
    subPlan.tail = startVidPlan.tail == nullptr ? loop : startVidPlan.tail;

return subPlan;
}
```

Go 語句生成的子執行計劃如下：
```
Start -> GetNeighbors -> Project -> Dedup -> Loop -> GetNeighbors -> Project -> GetVertices -> Project -> LeftJoin -> Filter -> Project
```

Go 語句的功能是完成圖的擴充，GetNeighbors 是執行計劃中最重要的節點，GetNeighbors 運算元會在執行期訪問儲存服務，拿到透過起點和指定邊型別一步擴充後終點的 id，多步擴充透過 Loop 節點實現，Start 到 Loop 之間是 Loop 子計劃，當滿足條件時 Loop 子計劃會被迴圈執行，最後一步擴充節點在 Loop 外實現。Project 節點用來獲取當前擴充的終點 id，Dedup 節點對終點 id 進行去重後作為下一步擴充的起點。GetVertices 節點負責取終點 tag 的屬性，Filter 做條件過濾，LeftJoin 的作用是合併 GetNeightbors 和 GetVertices 的結果。

OrderBy 語句的功能是對資料進行排序，子執行計劃會生成 Sort 節點。

左右子句計劃生成之後，PipeValidator::toPlan() 函式會呼叫 Validator::appendPlan() 連線左右子計劃並得到最終的執行計劃。完整執行計劃如下：
```
Start -> GetNeighbors -> Project -> Dedup -> Loop -> GetNeighbors -> Project -> GetVertices -> Project -> LeftJoin -> Filter -> Project -> Sort -> DataCollect 
```

以上 Validator 部分就介紹完畢。

### 論壇相關問題

> 問：如何找尋 parser/GraphParser.hpp 檔案

答：.h 檔案是由編譯時產生的檔案，編譯一次就有檔案了。

以上為本篇文章的介紹內容。

交流圖資料庫技術？加入 Nebula 交流群請先[填寫下你的 Nebula 名片](https://wj.qq.com/s2/8321168/8e2f/)，Nebula 小助手會拉你進群~~</gocontext></subplan></sequentialsentences></int64_t>

Nebula Graph 原始碼解讀系列｜ Vol.02 詳解 Validator

相關文章

Nebula Graph 原始碼解讀系列 ｜ Vol.02 詳解 Validator

相關文章

Nebula Graph 原始碼解讀系列｜ Vol.02 詳解 Validator