社区的小伙伴大多数都是通过文档来上手 NebulaGraph 自研的查询语言——nGQL，而 nGQL 因为是自研的查询语言的缘故，虽然它是一个声明式、同编程思维类似的查询语言，但是依旧是一个需要一点学习成本的语言。因此，NebulaGraph 文档对每个子句的用法给出了大量的示例，比如 MATCH 子句的用法：
nebula> MATCH (v) \
WITH v, properties(v) as props, keys(properties(v)) as kk \
WHERE [i in kk where props[i] == "Tim Duncan"] \
RETURN v;
+----------------------------------------------------+
| v |
+----------------------------------------------------+
| ("player100" :player{age: 42, name: "Tim Duncan"}) |
+----------------------------------------------------+
nebula> WITH ['Tim Duncan', 'Yao Ming'] AS names \
MATCH (v1:player)-->(v2:player) \
WHERE v1.player.name in names \
RETURN v1, v2;
+----------------------------------------------------+----------------------------------------------------------+
| v1 | v2 |
+----------------------------------------------------+----------------------------------------------------------+
| ("player133" :player{age: 38, name: "Yao Ming"}) | ("player114" :player{age: 39, name: "Tracy McGrady"}) |
| ("player133" :player{age: 38, name: "Yao Ming"}) | ("player144" :player{age: 47, name: "Shaquille O'Neal"}) |
| ("player100" :player{age: 42, name: "Tim Duncan"}) | ("player101" :player{age: 36, name: "Tony Parker"}) |
| ("player100" :player{age: 42, name: "Tim Duncan"}) | ("player125" :player{age: 41, name: "Manu Ginobili"}) |
+----------------------------------------------------+----------------------------------------------------------+
读到这里，细心的小伙伴可能发现了一个问题，这两个示例在干嘛？WITH 子句有用什么功能？
没错，文档虽然给出了很多用法示例，但是对每个语句缺少语句讲解，让每个语句被阅读的人更快地理解到它的作用，这对新手尤其重要，可以让他们在各个语句的作用中快速了解子句的查询表达力。
因此，即日开始至 2024.03.31 期间，便是 NebulaGraph 查询语句注释时间。希望我们度过这个寒冬之后，能在明媚的春天看到不一样的 nebula-docs。
活动介绍
在本次语句添加注释活动中，你可以给现有的 NebulaGraph 文档添加注释，因为 NebulaGraph 版本众多。本次活动选用最新的 master 版本，根据现有文档的设定，这些内容将会出现在后面最新的发行版中。
如何快速添加注释
因为 NebulaGraph 文档内容较多，如果拷贝到本地所需时间较长，建议直接在单个文档页面进行页面级别的 pr 提交。具体步骤参考：
-
Step 1: 打开 master 文档：https://docs.nebula-graph.com.cn/master/ ；
-
Step 2：找到你熟悉的子句页面，点击右上角的铅笔图标；
-
Step 3：编写语句注释。以表示注释的符号
#为开头，后面跟着你对这条语句的作用描述； -
Step 4：完成单个语句的修改之后，补充本次变更概述信息，提交 pr；
到现在，你的注释 pr 已经完成提交，坐等 nebula-docs 的维护者对 pr 进行 review、merge。
请查收你的 pr 奖励
你为 NebulaGraph 文档提交的注释 pr 被合并之后，自然成为 NebulaGraph 的 contributor（如果你之前从未提过 pr 并被合并）。
实物礼
下图为常规的 contributor 礼：
- 带有你 contributor 编号的实体证书；
- 纪念这个历史时刻的 contributor 马克杯；
此外，还有额外的限量不再生产的兔年吉祥物——星云兔（谐音：星云图），以及有重量的不可背锅钥匙扣。
电子礼
除了上述实体礼之外，按照你提交的语句注释数（注意不是 pr 数量）获得不同的徽章及称谓：
- 注释员：在本次活动中提交 1 个语句注释（对应 pr 被合并）
- 金牌注释员：在本次活动中提交 5+ 个语句注释（对应 pr 需要被合并）
而你所获得的徽章将展示在你的回复中：
为了将 GitHub ID 和论坛账号关联上，更好地颁发徽章，建议提交 pr 之后回复本帖，并附上对应的 pr 链接；
所有参与本次活动的小伙伴（提交过 pr）将会在本帖中被记录，以感谢你对文档语句可读性做出的贡献。
王者礼
本次活动写注释条数 Top 3 的小伙伴（对应的 pr 需要被合并），将额外得到 nStar 卫衣外套 x1 和双肩包 x1 一份：
注释书写规范
文档有一定的书写规范，写注释的时候请参考——中文文案排版指北
文档注释史
-
2024.03.03 knqiufan（GitHub ID： knqiufan）提交了一个
MATCH语句的示例注释 #pr2491 当中添加了 13 条注释； -
2024.02.29 yang-hub（GitHub ID： yang-hub）提交了一个
MATCH语句的示例注释 #pr2490 当中添加了 2 条注释（虽然该注释随后被 knqiufan 的 PR 替换）； -
2024.01.29 knqiufan（GitHub ID： knqiufan）提交了一个
SET语句的示例注释 #pr2433 当中添加了 7 条注释； -
2024.01.11 knqiufan（GitHub ID： knqiufan）提交了一个
comparison语句的示例注释 #pr2417 当中添加了 8 条注释； -
2024.01.18 knqiufan（GitHub ID： knqiufan）提交了一个
WITH语句的示例注释 #pr2418 当中添加了 6 条注释； -
2024.01.02 MuYiYong（GitHub ID： MuYiYong）提交了一个
MATCH语句的示例注释 #pr2411 当中添加了 4 条注释； -
2023.12.29 JialuGong（GitHub ID：JialuGong）提交了一个
2String语句的示例注释 #pr2410 当中添加了 20 条注释； -
2023.12.29 Big-Wuu（GitHub ID：Big-Wuu）提交了一个
MATCH语句的示例注释 #pr2409 当中添加了 2 条注释； -
2023.12.26 knqiufan（GitHub ID： knqiufan）提交了一个
aggregating语句的示例注释 #pr2402 当中添加了 13 条注释、一个arithmetic语句的示例注释 #pr2401 当中添加了 3 条注释、一个list语句的示例注释 #pr2400 当中添加了 5 条注释、一个string语句的示例注释 #pr2399 当中添加了 8 条注释、一个type-conversion语句的示例注释 #pr2398 当中添加了 2 条注释； -
2023.12.21 @E2ern1ty（GitHub ID：E2ern1ty）提交了一个
FIND PATH语句的示例注释 #pr2397 当中添加了 5 条注释； -
2023.12.15 aqzwy（GitHub ID：aqzwy）提交了一个
OPTIONAL MATCH语句的示例注释 #pr2396 当中添加了 2 条注释； -
2023.12.14 Driskoll（GitHub ID： Driskoll）提交了一个
GET SUBGRAPH语句的示例注释 #pr2394 -
2023.12.06 knqiufan（GitHub ID： knqiufan）提交了一个
FETCH语句的示例注释 #pr2389 添加了 9 条注释、一个LOOK UP语句的示例注释 #pr2388 添加了 23 条注释； -
2023.11.27 steam（GitHub ID：QingZ11）提交了一个 MATCH 语句的示例注释 #pr2374
