Skip to content

Add syntax snippets #1390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 7 commits into
base: dev
Choose a base branch
from
Draft

Add syntax snippets #1390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1c0300c
Add first round of grammar snippets
nvitucci Sep 17, 2025
411485c
Merge branch 'dev' into add-syntax-snippets
nvitucci Sep 17, 2025
23d449c
Add first round of railroad diagrams
nvitucci Sep 17, 2025
0b130fa
Test commit for deployment
nvitucci Sep 18, 2025
1f589d2
Add example of full grammar
nvitucci Sep 24, 2025
ab9c985
Fix whole grammar
nvitucci Sep 30, 2025
8a3242b
Merge branch 'dev' into add-syntax-snippets
nvitucci Sep 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/ROOT/content-nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@
*** xref:appendix/gql-conformance/supported-optional.adoc[]
*** xref:appendix/gql-conformance/analogous-cypher.adoc[]
*** xref:appendix/gql-conformance/additional-cypher.adoc[]
** xref:appendix/grammar/index.adoc[]
** xref:appendix/tutorials/index.adoc[]
*** xref:appendix/tutorials/basic-query-tuning.adoc[]
*** xref:appendix/tutorials/advanced-query-tuning.adoc[]
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/call-procedure.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<call procedure statement> ::=
[ "OPTIONAL" ] "CALL" <procedure call>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/create.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<create statement> ::=
"CREATE" <create graph pattern>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/delete.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<delete statement> ::=
[ "DETACH" | "NODETACH" ] "DELETE" <delete item list>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/filter.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<filter statement> ::=
"FILTER" [ "WHERE" ] <search condition>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/foreach.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<foreach statement> ::=
"FOREACH" "(" <foreach element source> <foreach action> ")"
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/let.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<let statement> ::=
"LET" <let variable definition list>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/limit.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<limit clause> ::=
"LIMIT" <value expression>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/load-csv.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<load csv statement> ::=
"LOAD CSV" [ "WITH HEADERS" ] <csv source> [ <csv field terminator> ]
12 changes: 12 additions & 0 deletions modules/ROOT/examples/syntax/clauses/match.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<simple match statement> ::=
"MATCH" <graph pattern>

<graph pattern> ::=
[ <match mode> ] <path pattern> [ { "," <path pattern> }... ] [ <graph pattern where clause> ]

<match mode> ::=
"REPEATABLE" { "ELEMENT" [ "BINDINGS" ] | "ELEMENTS" }
| "DIFFERENT" { "RELATIONSHIP" [ "BINDINGS" ] | "RELATIONSHIPS" }

<path pattern> ::=
[ <identifier> "=" ] [ <path pattern prefix> ] <path pattern expression>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/merge.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<merge statement> ::=
"MERGE" <merge graph pattern> [ <merge action> ]
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/optional-match.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<optional match statement> ::=
"OPTIONAL" <optional match operand>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/order-by.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<order by clause> ::=
"ORDER BY" <sort specification list>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/remove.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<remove statement> ::=
"REMOVE" <remove item list>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/return.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<return statement> ::=
"RETURN" <return statement body> [ <order by and page clause> ]
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/set.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<set statement> ::=
"SET" <set item list>
9 changes: 9 additions & 0 deletions modules/ROOT/examples/syntax/clauses/show-functions.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<show functions statement> ::=
"SHOW" [ "ALL" | "BUILT IN" | "USER DEFINED" ] { "FUNCTION" | "FUNCTIONS" } [ <executable by> ] [ <show result clause> ]

<executable by> ::=
"EXECUTABLE" [ "BY CURRENT USER" | "BY" <user name> ]

<show result clause> ::=
"YIELD" <yield item list> [ <order by clause> ] [ <offset clause> ] [ <limit clause> ] [ <where clause> ] [ <return statement> ]
| <where clause>
Copy link
Collaborator

@Hunterness Hunterness Sep 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do find it interesting that we portray <show result clause> differently in different places

for comparison, indexes:
image

(doesn't really mattter I guess, but I did check only two places and they happened to differ for the same thing :P)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I prefer the show functions way over the show index way)

2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/show-procedures.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<show procedures statement> ::=
"SHOW" <procedure keywords> [ <executable by> ] [ <show result clause> ]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comparing this to the show functions one, I like that one better.

  1. functions have { "FUNCTION" | "FUNCTIONS" } vs the procedures <procedure keywords> which is then not further defined :(
  2. the functions page also shows the <executable by> and <show result clause> rules, the procedure one leaves them out :( Might be nicer to also specify them in the procedure snippet

2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/show-settings.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<show settings statement> ::=
"SHOW" <setting keywords> [ <character string list element list or expression> ] [ <show result clause> ]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

similar as for the procedures, we don't give the <setting keywords> or <show result clause> definitions :(

6 changes: 6 additions & 0 deletions modules/ROOT/examples/syntax/clauses/show-transactions.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<show transactions statement> ::=
"SHOW" { "TRANSACTION" | "TRANSACTIONS" } [ <character string list element list or expression> ] [ <show result clause> ]

<show result clause> ::=
"YIELD" <yield item list> [ <order by clause> ] [ <offset clause> ] [ <limit clause> ] [ <where clause> ] [ <return statement> ]
| <where clause>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/skip.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<offset clause> ::=
<offset synonym> <value expression>
5 changes: 5 additions & 0 deletions modules/ROOT/examples/syntax/clauses/terminate-transactions.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<terminate transaction statement> ::=
"TERMINATE" { "TRANSACTION" | "TRANSACTIONS" } <character string list element list or expression> [ <show yield result clause> ]

<show yield result clause> ::=
"YIELD" <yield item list> [ <order by clause> ] [ <offset clause> ] [ <limit clause> ] [ <where clause> ] [ <return statement> ]
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/unwind.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<unwind statement> ::=
"UNWIND" <value expression> "AS" <binding variable>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/use.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<use graph clause> ::=
"USE" <graph expression>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/where.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<where clause> ::=
"WHERE" <search condition>
2 changes: 2 additions & 0 deletions modules/ROOT/examples/syntax/clauses/with.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<with statement> ::=
"WITH" <return statement body> [ <order by and page clause> ] [ <where clause> ]
62 changes: 62 additions & 0 deletions modules/ROOT/examples/syntax/constraints/create.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
<create constraint statement> ::=
"CREATE CONSTRAINT" [ <constraint name> | <general parameter reference> ] [ "IF NOT EXISTS" ] <constraint specification> [ <command options> ]

<command options> ::=
"OPTIONS" <map value or parameter specification>

<property names specification> ::=
<property name specification>
| "(" <property name specification> [ { "," <property name specification> }... ] ")"

<property name specification> ::=
<binding variable> "." <property name>

<constraint specification> ::=
<node constraint specification>
| <relationship constraint specification>

<node constraint specification> ::=
<node key constraint>
| <node uniqueness constraint>
| <node property existence constraint>
| <node property type constraint>

<relationship constraint specification> ::=
<relationship key constraint>
| <relationship uniqueness constraint>
| <relationship property existence constraint>
| <relationship property type constraint>

<node key constraint> ::=
"FOR" <command node pattern> "REQUIRE" <property names specification> "IS" [ "NODE" ] "KEY"

<node uniqueness constraint> ::=
"FOR" <command node pattern> "REQUIRE" <property names specification> "IS" [ "NODE" ] "UNIQUE"

<node property existence constraint> ::=
"FOR" <command node pattern> "REQUIRE" <property name specification> "IS NOT NULL"

<node property type constraint> ::=
"FOR" <command node pattern> "REQUIRE" <property name specification> { [ "IS" ] "::" | "IS TYPED" } <value type>

<relationship key constraint> ::=
"FOR" <command relationship pattern> "REQUIRE" <property names specification> "IS" [ "RELATIONSHIP" | "REL" ] "KEY"

<relationship uniqueness constraint> ::=
"FOR" <command relationship pattern> "REQUIRE" <property names specification> "IS" [ "RELATIONSHIP" | "REL" ] "UNIQUE"

<relationship property existence constraint> ::=
"FOR" <command relationship pattern> "REQUIRE" <property name specification> "IS NOT NULL"

<relationship property type constraint> ::=
"FOR" <command relationship pattern> "REQUIRE" <property name specification> { [ "IS" ] "::" | "IS TYPED" } <value type>

<command node pattern> ::=
"(" <binding variable> ":" <label name> ")"

<command relationship pattern> ::=
"()" { "<-[" <binding variable> ":" <label name> "]-" | "-[" <binding variable> ":" <label name> "]->" | "<-[" <binding variable> ":" <label name> "]->" | "-[" <binding variable> ":" <label name> "]-" } "()"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some places (like this and some of the index ones) have it like this and others have it split:

<command relationship pattern> ::= 
  "()" { "<" <command relationship body> | <command relationship body> ">" | "<" <command relationship body> ">" | <command relationship body> } "()"

<command relationship body> ::= 
  "-[" <binding variable> ":" <label name> "]-"

Might be nice to be consistent?


<map value or parameter specification> ::=
<map value constructor>
| <general parameter reference>
6 changes: 6 additions & 0 deletions modules/ROOT/examples/syntax/constraints/drop.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
<drop constraint statement> ::=
"DROP CONSTRAINT" <constraint name specification> [ "IF EXISTS" ]

<constraint name specification> ::=
<constraint name>
| <general parameter reference>
24 changes: 24 additions & 0 deletions modules/ROOT/examples/syntax/constraints/show.bnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<show constraints statement> ::=
"SHOW" [ <show constraint type> ] <constraint keywords> [ <show result clause> ]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

more <_ keywords> rules that probably should be inlined, and <show result clause> that should be defined


<show constraint type> ::=
<show all constraints>
| <show key constraints>
| <show uniqueness constraints>
| <show property existence constraints>
| <show property type constraints>

<show all constraints> ::=
"ALL"

<show key constraints> ::=
[ "NODE" | "RELATIONSHIP" | "REL" ] "KEY"

<show uniqueness constraints> ::=
[ "NODE" | "RELATIONSHIP" | "REL" ] [ "PROPERTY" ] { "UNIQUENESS" | "UNIQUE" }

<show property existence constraints> ::=
[ "NODE" | "RELATIONSHIP" | "REL" ] [ "PROPERTY" ] { "EXISTENCE" | "EXIST" }

<show property type constraints> ::=
[ "NODE" | "RELATIONSHIP" | "REL" ] "PROPERTY TYPE"
Loading