![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/ngql-cheatsheet-cn-01.jpg)

本文旨在讓新手快速瞭解 nGQL，掌握方向，之後可以腳踩在地上藉助文件寫出任何心中的 NebulaGraph 圖查詢。

## 影片

本教程的影片版在[B站這裡](https://bilibili.com/video/BV1PT411P7w8)。

## 準備工作

在正式開始 nGQL 實操之前，記得先**看過文件「快速入門流程」，部署、連線過 NebulaGraph，並且看過了「常用命令」**。如果你還沒看過這兩個文件，為了跟上進度，記得先快速過一遍，上面兩個文件連結可在文末「參考資料」中獲取。

### 我們的目標是

本教程目的在於讓大家大概知道了 NebulaGraph 的查詢語句後，解決“不知道什麼樣的查詢應該用什麼語句”的問題。

### nGQL 是什麼

我們先強調一下概念：nGQL 是 NebulaGraph Query Language 的縮寫，它表示 NebulaGraph 的查詢語言，可以不嚴謹地分為這 5 部分：

- NebulaGraph 獨有 DQL（Data Query Language）查詢語句
- NebulaGraph openCypher DQL
- NebulaGraph DML（Data Mutation Language）寫語句
- NebulaGraph DDL（Data Definition Language) Schema 語句
- NebulaGraph Admin Queries 管理語句

這裡，作為簡明教程一把梭，我們只關注前兩個部分，後邊的內容會在 Part 2 中介紹。

### nGQL 速查表 cheatsheet

大家可以儲存下這份單頁速查表，一次瞭解所有 nGQL 的用法。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-blog/ngql-cheatsheet-cn.webp)

## NebulaGraph 獨有 DQL

NebulaGraph 的獨有讀查詢語句的設計非常簡潔，對初學者非常友好。它結合了管道的概念，做到了只涉及了幾個關鍵詞就可以描述出大多數的圖查詢模式。**由於篇幅的問題，所有 DQL 查詢語句的更多用法記得查閱本文的「參考資料」**。

簡單來說，nGQL 的獨有 DQL 一共分成四類語句：

- 圖擴充 / 遍歷：`GO`
- 索引反查：`LOOKUP`
- 取屬性：`FETCH`
- 路徑與子圖：`FIND PATH` 與 `GET SUBGRAPH`

和兩個特別的元素：

- 管道：`|`
- 引用屬性: `$` 開頭的幾個符號，用來描述一些特定的上下文

### 用 GO 來圖擴充 / 遍歷

`GO` 的語義非常直觀：從**給定的起點**，向外擴充，按需**返回終點**、起點的資訊。

```sql
# 圖擴充
GO 3 STEPS FROM "player102" OVER follow YIELD dst(edge);
   ───┬───      ───┬───────      ─┬────       ──┬────── 
      │            │              │   ┌─────────┘       
      │            │              │   │                 
      │            │              │   └── 返回最後一跳邊的終點
      │            │              │                     
      │            │              └────── 從 follow 這個邊[出方向]探索
      │            │                                    
      │            └───────────────────── 起點是 "player102"
      │                                                 
      └────────────────────────────────── 探索 3 步
```

這裡只是做了一個簡單的 `GO` 語法示例，像 GO 實現的反向、雙向擴充，指定可變跳數遍歷等，更多 GO 語句用法可查閱參考資料。

### LOOKUP 基於索引反查 ID

和 `GO` 的從已知的點出發相反，`LOOKUP` 是一個類似於 SQL 裡 `SELECT` 語義的關鍵字，它**實際的作用也類似與關係型資料庫中的掃表**。

`LOOKUP` **需要手動建立相應 TAG、邊型別上索引才能進行相關查詢**。

#### 為什麼 `LOOKUP` 需要索引？

因為 NebulaGraph 中的資料預設是按照鄰接表的形式儲存，在分散式設計中，掃描一個型別的點、邊是非常昂貴的，所以它被預設禁止了。NebulaGraph 索引的存在增加了類似於表結構資料庫的排序資料，可以用來做像是 `SELECT` 的查詢。

```sql
# 索引反查
LOOKUP ON player WHERE player.name == "Tony Parker" YIELD id(vertex);
          ──┬───  ──────┬──────────────────────────  ──┬──────       
            │           │          ┌───────────────────┘             
            │           │          │                                 
            │           │          └──────────── 返回查到點的 VID
            │           │                                            
            │           └─────────────────────── 過濾條件是屬性 name 的值
            │                                                        
            └─────────────────────────────────── 根據點的類別/TAG player 查詢
```

本文僅作 LOOKUP 語法的使用入門，關於索引原理和使用，比如：建立索引會有什麼代價？索引會加速讀麼？記得檢視文末的參考資料。

### FETCH PROP 獲取屬性

如字面意思，如果我們知道一個點、邊的 ID，想要獲取它上邊的屬性，這時候我們要用 `FETCH PROP` 而非 `LOOKUP`。

```sql
# 取屬性
FETCH PROP ON player "player100" YIELD properties(vertex);
              ──┬───  ────┬─────       ─────────┬──────── 
                │         │         ┌───────────┘         
                │         │         │                     
                │         │         └─────── 返回點的 player TAG 下所有屬性
                │         │                               
                │         └───────────────── 從 "player100" 這個點獲取
                │                                         
                └─────────────────────────── 獲取 player 這個 TAG 下的屬性
```

### 路徑查詢 FIND PATH

如果我們要找到指定兩點之間的所有路徑，一定要用 `FIND PATH`。

```sql
# 起點終點間路徑
FIND SHORTEST PATH FROM "player102" TO "team204" OVER * \   
     ──┬─────            ───────────┬─────────── ───┬───    
  YIELD│path AS p; ┌────────────────┘               │       
       │────┬────  │     ┌──────────────────────────┘       
       │    │      │     │                                  
       │    │      │     └───────── 經由所有型別的邊出向探索
       │    │      │                                        
       │    │      └─────────────── 從給定的起點、終點 VID
       │    │                                               
       │    └────────────────────── 返回路徑為 p 列
       │                                                    
       └─────────────────────────── 查詢最短路徑
```

### 單點子圖 GET SUBGRAPH

和路徑查詢類似，如果我們只給定一個起點和擴充步數，用 `GET SUBGRAPH` 可以幫我們獲取同樣的 BFS 出去的子圖。

```sql
# 單點 BFS 子圖

GET SUBGRAPH 5 STEPS FROM "player101" \           
             ───┬─── ─────┬──────────             
  YIELD VERTICES AS nodes, EDGES AS relationships;
        ────┬───┼─────────┼───────────────────────
   ┌────────┘   │         │                       
   │            │         └─────── 從 "player101" 開始觸發
   │            │                                 
   │            └───────────────── 獲取 5 步的探索
   │                                              
   └────────────────────────────── 返回所有的點、邊
```

### 利用管道和屬性引用符

NebulaGraph 的管道設計和 Unix-Shell 的設計很像，可以將簡單的幾種語句結合起來，有強大的表達力。

```sql
# 使用通道
GO FROM "player100" OVER follow YIELD dst(edge) AS did  | \  
    ─────┬──────────────────────────────────────────── ─┬─   
  GO FROM│$-.did OVER follow YIELD dst(edge);           │    
         │────┬──     ┌─────────────────────────────────┘    
         │    │       │                                      
         │    │       └──────── 管道將左邊的 AS 輸出作為右邊語句輸入
         │    │                                              
         │    └──────────────── 從管道左邊的 did 屬性開始探索
         │
         └───────────────────── 第一個查詢語句
```

除了以上的集中表達之外，NebulaGraph 獨有查詢語句還有聚合的表達參考 `GROUP-BY`，另外在文件裡還有一個 `Cheatsheet`供大家查詢一些複雜的例子。

## NebulaGraph openCypher DQL

從 NebulaGraph v2.0 起，openCypher 的 `MATCH` 語句也被 NebulaGraph 原生支援了。雖然 NebulaGraph 這裡是一個“方言”，有一些使用細節差異。

```
MATCH <pattern> [<clause_1>] RETURN <output>  [<clause_2>];
```

MATCH 的基本表達是由 `(v:tag_a)` 包裹的點和 `-->` 或者 `(v2)(n) WHERE id(m)=="player100" \
OPTIONAL MATCH (n)-[]->(l) WHERE id(n)=="player125" \
    RETURN id(m), id(n), id(l);
```

以上，為本次簡明教程的第一集。

## 參考資料

* 快速入門 NebulaGraph：[https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/1.quick-start-workflow/](https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/1.quick-start-workflow/)
* nGQL 常見命令：[https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/4.nebula-graph-crud/](https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/4.nebula-graph-crud/)
* GO 語句文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/3.go/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/3.go/)
* 全方位講解 NebulaGraph 索引原理和使用：[https://discuss.nebula-graph.com.cn/t/topic/8074](https://discuss.nebula-graph.com.cn/t/topic/8074)
* LOOKUP 語句文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/5.lookup/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/5.lookup/)
* FETCH PROP 語句文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/4.fetch/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/4.fetch/)
* GET SUBGRAPH 語句文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/16.subgraph-and-path/1.get-subgraph/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/16.subgraph-and-path/1.get-subgraph/)
* 管道 ｜ 文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/5.operators/4.pipe/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/5.operators/4.pipe/)
* 引用符 $ 文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/5.operators/5.property-reference/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/5.operators/5.property-reference/)
* GROUP-BY：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/8.clauses-and-options/group-by/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/8.clauses-and-options/group-by/)
* nGQL Cheatsheet：[https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/6.cheatsheet-for-ngql-command/](https://docs.nebula-graph.com.cn/3.2.0/2.quick-start/6.cheatsheet-for-ngql-command/)
* MATCH 語句文件：[https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/2.match/](https://docs.nebula-graph.com.cn/3.2.0/3.ngql-guide/7.general-query-statements/2.match/)

----

**謝謝你讀完本文** (///▽///)

免部署省時省力，現在可以用用 NebulaGraph Cloud 來搭建自己的圖資料系統喲~NebulaGraph 阿里雲端計算巢現 30 天免費使用中，[點選連結](http://c.nxw.so/7wtsN)來用用圖資料庫吧~

想看原始碼的小夥伴可以前往 GitHub 閱讀、使用、(^з^)-☆ star 它 -> [GitHub](http://c.nxw.so/8yTlk)；和其他的 NebulaGraph 使用者一起交流圖資料庫技術和應用技能，留下[「你的名片」](http://c.nxw.so/9jvQN)一起玩耍呢~</clause_2></output></clause_1></pattern>

圖查詢語言 nGQL 簡明教程 vol.01 快速入門

相關文章