nGQL style guide¶

nGQL does not have strict formatting requirements, but creating nGQL statements according to an appropriate and uniform style can improve readability and avoid ambiguity. Using the same nGQL style in the same organization or project helps reduce maintenance costs and avoid problems caused by format confusion or misunderstanding. This topic will provide a style guide for writing nGQL statements.

Compatibility

The styles of nGQL and Cypher Style Guide are different.

Newline¶

Start a new line to write a clause.

Not recommended:

GO FROM "player100" OVER follow REVERSELY YIELD src(edge) AS id;

Recommended:

GO FROM "player100" \
OVER follow REVERSELY \
YIELD src(edge) AS id;

Start a new line to write different statements in a composite statement.

Not recommended:

GO FROM "player100" OVER follow REVERSELY YIELD src(edge) AS id | GO FROM $-.id \
OVER serve WHERE properties($^).age > 20 YIELD properties($^).name AS FriendOf, properties($$).name AS Team;

Recommended:

GO FROM "player100" \
OVER follow REVERSELY \
YIELD src(edge) AS id | \
GO FROM $-.id OVER serve \
WHERE properties($^).age > 20 \
YIELD properties($^).name AS FriendOf, properties($$).name AS Team;

If the clause exceeds 80 characters, start a new line at the appropriate place.

Not recommended:

MATCH (v:player{name:"Tim Duncan"})-[e]->(v2) \
WHERE (v2.player.name STARTS WITH "Y" AND v2.player.age > 35 AND v2.player.age < v.player.age) OR (v2.player.name STARTS WITH "T" AND v2.player.age < 45 AND v2.player.age > v.player.age) \
RETURN v2;

Recommended:

MATCH (v:player{name:"Tim Duncan"})-[e]->(v2) \
WHERE (v2.player.name STARTS WITH "Y" AND v2.player.age > 35 AND v2.player.age < v.player.age) \
OR (v2.player.name STARTS WITH "T" AND v2.player.age < 45 AND v2.player.age > v.player.age) \
RETURN v2;

Note

If needed, you can also start a new line for better understanding, even if the clause does not exceed 80 characters.

Identifier naming¶

In nGQL statements, characters other than keywords, punctuation marks, and blanks are all identifiers. Recommended methods to name the identifiers are as follows.

Use singular nouns to name tags, and use the base form of verbs or verb phrases to form Edge types.

Not recommended:
```
MATCH p=(v:players)-[e:are_following]-(v2) \
RETURN nodes(p);
```
Recommended:
```
MATCH p=(v:player)-[e:follow]-(v2) \
RETURN nodes(p);
```
Use the snake case to name identifiers, and connect words with underscores (_) with all the letters lowercase.

Not recommended:
```
MATCH (v:basketballTeam) \
RETURN v;
```
Recommended:
```
MATCH (v:basketball_team) \
RETURN v;
```
Use uppercase keywords and lowercase variables.

Not recommended:
```
match (V:player) return V limit 5;
```
Recommended:
```
MATCH (v:player) RETURN v LIMIT 5;
```

Pattern¶

Start a new line on the right side of the arrow indicating an edge when writing patterns.

Not recommended:

MATCH (v:player{name: "Tim Duncan", age: 42}) \
-[e:follow]->()-[e:serve]->()<--(v2) \
RETURN v, e, v2;

Recommended:

MATCH (v:player{name: "Tim Duncan", age: 42})-[e:follow]-> \
()-[e:serve]->()<--(v2) \
RETURN v, e, v2;

Anonymize the vertices and edges that do not need to be queried.

Not recommended:
```
MATCH (v:player)-[e:follow]->(v2) \
RETURN v;
```
Recommended:
```
MATCH (v:player)-[:follow]->() \
RETURN v;
```
Place named vertices in front of anonymous vertices.

Not recommended:
```
MATCH ()-[:follow]->(v) \
RETURN v;
```
Recommended:
```
MATCH (v)<-[:follow]-() \
RETURN v;
```

String¶

The strings should be surrounded by double quotes.

Not recommended:

RETURN 'Hello Nebula!';

Recommended:

RETURN "Hello Nebula!\"123\"";

Note

When single or double quotes need to be nested in a string, use a backslash () to escape. For example:

RETURN "\"NebulaGraph is amazing,\" the user says.";

Statement termination¶

End the nGQL statements with an English semicolon (;).

Not recommended:

FETCH PROP ON player "player100" YIELD properties(vertex)

Recommended:

FETCH PROP ON player "player100" YIELD properties(vertex);

Use a pipe (|) to separate a composite statement, and end the statement with an English semicolon at the end of the last line. Using an English semicolon before a pipe will cause the statement to fail.

Not supported:

GO FROM "player100" \
OVER follow \
YIELD dst(edge) AS id; | \
GO FROM $-.id \
OVER serve \
YIELD properties($$).name AS Team, properties($^).name AS Player;

Supported:

GO FROM "player100" \
OVER follow \
YIELD dst(edge) AS id | \
GO FROM $-.id \
OVER serve \
YIELD properties($$).name AS Team, properties($^).name AS Player;

In a composite statement that contains user-defined variables, use an English semicolon to end the statements that define the variables. If you do not follow the rules to add a semicolon or use a pipe to end the composite statement, the execution will fail.

Not supported:

$var = GO FROM "player100" \
OVER follow \
YIELD follow._dst AS id \
GO FROM $var.id \
OVER serve \
YIELD $$.team.name AS Team, $^.player.name AS Player;

Not supported:

$var = GO FROM "player100" \
OVER follow \
YIELD follow._dst AS id | \
GO FROM $var.id \
OVER serve \
YIELD $$.team.name AS Team, $^.player.name AS Player;

Supported:

$var = GO FROM "player100" \
OVER follow \
YIELD follow._dst AS id; \
GO FROM $var.id \
OVER serve \
YIELD $$.team.name AS Team, $^.player.name AS Player;

Last update: February 2, 2023