logo
咨询企业版

技术分享

nGQL 加注释,让这条查询语句更有可读性

nGQL 加注释 社区的小伙伴大多数都是通过文档来上手 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。

PART.01 活动介绍 在本次语句添加注释活动中,你可以给现有的 NebulaGraph 文档添加注释,因为 NebulaGraph 发行版众多。本次活动选用最新发行版(v3.6.0),根据现有文档的设定,最新发行版的内容将会同步到后续的发行版。这样,近期将会发布的 v3.7.0 也能收录你为 nGQL 编写的注释。

01 如何快速添加注释

因为 NebulaGraph 文档内容较多,如果拷贝到本地所需时间较长,建议直接在单个文档页面进行页面级别的 pr 提交。具体步骤参考:

Step 1: 打开最新发行版文档:https://docs.nebula-graph.com.cn/ ;

Step 2:找到你熟悉的子句页面,点击右上角的铅笔图标;图片

nGQL 加注释

Step 3:编写语句注释。以表示注释的符号 # 为开头,后面跟着你对这条语句的作用描述;

nGQL 加注释

Step 4:完成单个语句的修改之后,补充本次变更概述信息,提交 pr;

nGQL 加注释

nGQL

nGQL

到现在,你的注释 pr 已经完成提交,坐等 nebula-docs 的维护者对 pr 进行 review、merge。

02 请查收你的 pr 奖励

你为 NebulaGraph 文档提交的注释 pr 被合并之后,自然成为 NebulaGraph 的 contributor(如果你之前从未提过 pr 并被合并)。

实物礼

下图为常规的 contributor 礼:

  • 带有你 contributor 编号的实体证书;

  • 纪念这个历史时刻的 contributor 马克杯;

contributor 马克杯

此外,还有额外的限量不再生产的兔年吉祥物——星云兔(谐音:星云图),以及有重量的不可背锅钥匙扣。

星云兔

星云兔

电子礼

除了上述实体礼之外,按照你提交的语句注释数(注意不是 pr 数量)获得不同的徽章及称谓:

注释员:在本次活动中提交 1 个语句注释(对应 pr 被合并)

金牌注释员:在本次活动中提交 5+ 个语句注释(对应 pr 需要被合并)

为了将 GitHub ID 和论坛账号关联上,更好地颁发徽章,建议提交 pr 之后回复活动贴(参考「阅读原文」),并附上对应的 pr 链接;

所有参与本次活动的小伙伴(提交过 pr)将会在本帖中被记录,以感谢你对文档语句可读性做出的贡献。

王者礼 本次活动写注释条数 Top 3 的小伙伴(对应的 pr 需要被合并),将额外得到 nStar 卫衣外套 x1 和双肩包 x1 一份: nStar 卫衣外套

双肩包