From 9eaa571e10d8a00f94aff4fba611444f52c57653 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E6=99=93=E9=9D=92?= <86282370+izhuxiaoqing@users.noreply.github.com> Date: Tue, 13 Jul 2021 14:41:01 +0800 Subject: [PATCH 1/5] ngql style guide --- .../identifier-case-sensitivity.md | 2 +- .../1.nGQL-overview/ngql-style-guide.md | 257 ++++++++++++++++++ 2 files changed, 258 insertions(+), 1 deletion(-) create mode 100644 docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/identifier-case-sensitivity.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/identifier-case-sensitivity.md index 5edd6ef39af..0db9efb5b52 100644 --- a/docs-2.0/3.ngql-guide/1.nGQL-overview/identifier-case-sensitivity.md +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/identifier-case-sensitivity.md @@ -1,4 +1,4 @@ -# Identifier Case Sensitivity +# Identifier case sensitivity ## Identifiers are Case-Sensitive diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md new file mode 100644 index 00000000000..49e2b94373b --- /dev/null +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md @@ -0,0 +1,257 @@ +# 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](https://s3.amazonaws.com/artifacts.opencypher.org/M15/docs/style-guide.pdf) are different. + +## Newline and indentation + +1. Start a new line to write a clause. + + Not recommended: + + ```ngql + GO FROM "player100" OVER follow REVERSELY YIELD follow._dst AS id; + ``` + + Recommended: + + ```ngql + GO FROM "player100" \ + OVER follow REVERSELY \ + YIELD follow._dst AS id; + ``` + +2. Start a new line to write different statements in a composite statement. + + Not recommended: + + ```ngql + GO FROM "player100" OVER follow REVERSELY YIELD follow._dst AS id | GO FROM $-.id \ + OVER serve WHERE $^.player.age > 20 YIELD $^.player.name AS FriendOf, $$.team.name AS Team; + ``` + + Recommended: + + ```ngql + GO FROM "player100" \ + OVER follow REVERSELY \ + YIELD follow._dst AS id | \ + GO FROM $-.id OVER serve \ + WHERE $^.player.age > 20 \ + YIELD $^.player.name AS FriendOf, $$.team.name AS Team; + ``` + +3. If the clause exceeds 80 characters, start a new line at the appropriate place. + + Not recommended: + + ```ngql + MATCH (v:player{name:"Tim Duncan"})-[e]->(v2) \ + WHERE (v2.name STARTS WITH "Y" AND v2.age > 35 AND v2.age < v.age) OR (v2.name STARTS WITH "T" AND v2.age < 45 AND v2.age > v.age) \ + RETURN v2; + ``` + + Recommended: + + ```ngql + MATCH (v:player{name:"Tim Duncan"})-[e]->(v2) \ + WHERE (v2.name STARTS WITH "Y" AND v2.age > 35 AND v2.age < v.age) \ + OR (v2.name STARTS WITH "T" AND v2.age < 45 AND v2.age > v.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 nomenclature + +In nGQL statements, characters other than keywords, punctuation marks, and blanks are all identifiers. Recommended methods to name the identifiers are as follows. + +1. Use singular nouns to name tags, and use the base form of verbs or verb phrases to form Edge types. + + Not recommended: + + ```ngql + MATCH p=(v:players)-[e:are_following]-(v2) \ + RETURN nodes(p); + ``` + + Recommended: + + ```ngql + MATCH p=(v:player)-[e:follow]-(v2) \ + RETURN nodes(p); + ``` + +2. Use snake case to name the identifiers, and connect the words with underscores (_) with all the letters lowercase. + + Not recommended: + + ```ngql + MATCH (v:basketballTeam) \ + RETURN v; + ``` + + Recommended: + + ```ngql + MATCH (v:basketball_team) \ + RETURN v; + ``` + +## Pattern + +1. Start a new line on the right side of the arrow indicating an edge when writing patterns. + + Not recommended: + + ```ngql + MATCH (v:player{name: "Tim Duncan", age: 42}) \ + -[e:follow]->()-[e:serve]->()<--(v3) \ + RETURN v, e, v2; + ``` + + Recommended: + + ```ngql + MATCH (v:player{name: "Tim Duncan", age: 42})-[e:follow]-> \ + ()-[e:serve]->()<--(v3) \ + RETURN v, e, v2; + ``` + +2. Anonymize the vertices and edges that do not need to be queried. + + Not recommended: + + ```ngql + MATCH (v:player)-(e:follow)->(v2) \ + RETURN v; + ``` + + Recommended: + + ```ngql + MATCH (v:player)-(:follow)->() \ + RETURN v; + ``` + +3. Place non-anonymous vertices in front of anonymous vertices. + + Not recommended: + + ```ngql + MATCH ()-(:follow)->(v) \ + RETURN v; + ``` + + Recommended: + + ```ngql + MATCH (v)<-(:follow)-() \ + RETURN v; + ``` + +## String + +The strings should be surrounded by double quotes. + + Not recommended: + + ```ngql + RETURN 'Hello Nebula!'; + ``` + + Recommended: + + ```ngql + RETURN "Hello Nebula!\"123\""; + ``` + +!!! note + + When single or double quotes need to be nested in a string, use a backslash (\) to escape. For example: + + ```ngql + RETURN "\"Nebula Graph is amazing,\" the user says."; + ``` + + + +## Statement termination + +1. End the nGQL statements with an English semicolon (;). + + Not recommended: + + ```ngql + FETCH PROP ON player "player100" + ``` + + Recommended: + + ```ngql + FETCH PROP ON player "player100"; + ``` + +2. 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: + + ```ngql + GO FROM "player100" \ + OVER follow \ + YIELD follow._dst AS id; | \ + GO FROM $-.id \ + OVER serve \ + YIELD $$.team.name AS Team, $^.player.name AS Player; + ``` + + Supported: + + ```ngql + GO FROM "player100" \ + OVER follow \ + YIELD follow._dst AS id | \ + GO FROM $-.id \ + OVER serve \ + YIELD $$.team.name AS Team, $^.player.name AS Player; + ``` + +3. In a composite statement that contains customized 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: + + ```ngql + $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: + + ```ngql + $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: + + ```ngql + $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; + ``` From 0bde2f7fafea022f510b875e5027a764d0245637 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E6=99=93=E9=9D=92?= <86282370+izhuxiaoqing@users.noreply.github.com> Date: Tue, 13 Jul 2021 15:01:16 +0800 Subject: [PATCH 2/5] Update ngql-style-guide.md --- docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md index 49e2b94373b..f74e8fb51e2 100644 --- a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md @@ -221,7 +221,7 @@ The strings should be surrounded by double quotes. YIELD $$.team.name AS Team, $^.player.name AS Player; ``` -3. In a composite statement that contains customized 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. +3. 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: From 107f13a303c0a3ad45b375727961ad672b35b68f Mon Sep 17 00:00:00 2001 From: randomJoe211 <69501902+randomJoe211@users.noreply.github.com> Date: Tue, 13 Jul 2021 16:50:31 +0800 Subject: [PATCH 3/5] Update ngql-style-guide.md --- docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md index f74e8fb51e2..81080ec9e43 100644 --- a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md @@ -6,7 +6,7 @@ nGQL does not have strict formatting requirements, but creating nGQL statements The styles of nGQL and [Cypher Style Guide](https://s3.amazonaws.com/artifacts.opencypher.org/M15/docs/style-guide.pdf) are different. -## Newline and indentation +## Newline 1. Start a new line to write a clause. From f0c6f5b20c785a23494fe2196b6b5919836ef34d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E6=99=93=E9=9D=92?= <86282370+izhuxiaoqing@users.noreply.github.com> Date: Tue, 13 Jul 2021 17:15:06 +0800 Subject: [PATCH 4/5] Update ngql-style-guide.md --- docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md index f74e8fb51e2..3faf374e33b 100644 --- a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md @@ -87,7 +87,7 @@ In nGQL statements, characters other than keywords, punctuation marks, and blank RETURN nodes(p); ``` -2. Use snake case to name the identifiers, and connect the words with underscores (_) with all the letters lowercase. +2. Use the snake case to name identifiers, and connect words with underscores (_) with all the letters lowercase. Not recommended: @@ -139,7 +139,7 @@ In nGQL statements, characters other than keywords, punctuation marks, and blank RETURN v; ``` -3. Place non-anonymous vertices in front of anonymous vertices. +3. Place named vertices in front of anonymous vertices. Not recommended: From 3ec5a3582f019a916828e3c5d548838413727ba9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=B1=E6=99=93=E9=9D=92?= <86282370+izhuxiaoqing@users.noreply.github.com> Date: Wed, 14 Jul 2021 14:45:12 +0800 Subject: [PATCH 5/5] Update ngql-style-guide.md --- docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md index 2c643e4028d..1e6164095e8 100644 --- a/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md +++ b/docs-2.0/3.ngql-guide/1.nGQL-overview/ngql-style-guide.md @@ -67,7 +67,7 @@ nGQL does not have strict formatting requirements, but creating nGQL statements If needed, you can also start a new line for better understanding, even if the clause does not exceed 80 characters. -## Identifier nomenclature +## 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.