NebulaGraph Query Statements Commentary: to Enhance nGQL's Usability

Many community members learn NebulaGraph's proprietary query language, nGQL, via our documentation. While nGQL is a declarative, programming-style query language, its uniqueness necessitates some learning. To facilitate this, our NebulaGraph documentation provides plentiful examples for each clause, such as the MATCH clause usage.

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"})    |
+----------------------------------------------------+----------------------------------------------------------+

However, you might find yourself pondering over the examples: what exactly are these examples demonstrating? What's the purpose of the WITH clause?

In truth, while our documentation offers numerous usage examples, it lacks the explanatory notes for each statement that would make understanding their functionality much easier. This is particularly crucial for NebulaGraph novices since it helps them swiftly grasp the potential of the clauses. Therefore, we're excited to launch the community program, NebulaGraph Query Statements Commentary, with the aim of making nebula-docs more accessible with the assistance of our community members.

Program Overview

The program encourages you to add comments to the existing NebulaGraph documentation, specifically to v3.6.0, so that the forthcoming version v3.7.0 includes your nGQL comments. The program runs until March 31, 2024.

Efficient Commenting Process:

Instead of copying the entire documentation locally, which may be time-consuming, we recommend making page-level PR submissions directly on the individual document page. Here are the detailed steps:

Step 1: Access the master document at: https://docs.nebula-graph.io/3.6.0/
Step 2: Identify the clause page you're familiar with and click the pencil icon in the upper right corner.
Step 3: Write the statement comments and start the comment with the symbol #.
Step 4: After modifying a single statement, provide a summary of the changes and submit your PR.

The next step is to wait for the nebula-docs maintainers to review and merge your PR.

Claim Your PR Rewards

Contributor SWAG pack

If you're a first-time PR submitter to NebulaGraph and your comment PR has been merged, you automatically become a NebulaGraph contributor. As a contributor, you'll receive a certificate with your unique contributor number, a commemorative contributor mug and a limited edition Nebula Rabbit!

Special SWAGs for Top 3 Commenters

The top 3 participants who contribute the most comments (with corresponding merged PRs) will also receive an nStar hoodie and a backpack!

Get started now!