agens_graph_spec.md

AgensGraph

AgensGraph Data Definition Language - http://bitnine.net/support/quick-start-guide-html/

AgensGraph Cypher Query - http://www.agensgraph.com/agensgraph-docs/agensgraph_cypher_query.html

Cypher EBNF Representation - https://s3.amazonaws.com/artifacts.opencypher.org/cypher.ebnf

RailRoad Diagrams - https://s3.amazonaws.com/artifacts.opencypher.org/railroad/Cypher.html

Notation

• Statements such as [ stmt ] are optional
• , represents a sequence of states.

EBNF

AgensGraphReducedSet = [SP], Statement, [[SP], ';'], [SP], EOI ;

Statement = Query ;

Query = SingleQuery, { [SP], Union } ; (* we ignore standalone call here *)

Union = ((U,N,I,O,N), SP, (A,L,L), [SP], SingleQuery)
      | ((U,N,I,O,N), [SP], SingleQuery)
      ;

SingleQuery = ReadOnlyEnd (* we ignore MultiPartQuery standalone call here *)
            | ReadUpdateEnd
            | UpdatingEnd
            ; 

ReadOnlyEnd = ReadPart, Return ;

ReadUpdateEnd = ReadingClause, { [SP], ReadingClause }, { [SP], UpdatingClause }-, [[SP], Return] ;

UpdatingEnd = UpdatingStartClause, { [SP], UpdatingClause }, [[SP], Return] ;

ReadPart = { ReadingClause, [SP] } ;

UpdatingStartClause = Merge
                    | Create
                    | CreateLiteral
                    | DropLiteral
                    | (S,E,T), SP, (g,r,a,p,h,_,p,a,t,h,=), SP, Binding;
                    ;

GraphLiteral = (E,L,A,B,E,L)
             | (V,L,A,B,E,L)
             | (G,R,A,P,H)
             ;

CreateLiteral = (C,R,E,A,T,E), SP, GraphLiteral, SP, Binding;

DropLiteral = (D,R,O,P), SP, GraphLiteral, SP, Binding, [SP, Cascade];

Cascade = (C,A,S,C,A,D,E);

UpdatingClause = Create (* we are not using Remove and Union clauses here *)
               | Merge
               | Delete
               | Set
               ;

ReadingClause = Match (* we are not using InQueryCall. Unwind does not exist as well on agens *)
              ;

Match = [(O,P,T,I,O,N,A,L), SP], (M,A,T,C,H), [SP], Pattern, [[SP], Where] ;

Create = (C,R,E,A,T,E), [SP], Pattern ;

Merge = (M,E,R,G,E), [SP], PatternPart, { SP, MergeAction } ;

MergeAction = ((O,N), SP, (M,A,T,C,H), SP, Set)
            | ((O,N), SP, (C,R,E,A,T,E), SP, Set)
            ;

Delete = [(D,E,T,A,C,H), SP], (D,E,L,E,T,E), [SP], Expression, { [SP], ',', [SP], Expression } ;

Set = (S,E,T), [SP], SetItem, { ',', SetItem } ;

SetItem = (PropertyExpression, [SP], '=', [SP], Expression)
        | (Binding, [SP], '=', [SP], Expression)
        | (Binding, [SP], '+=', [SP], Expression)
        | (Binding, [SP], NodeLabels)
        ;
              
Return = (R,E,T,U,R,N), [[SP], (D,I,S,T,I,N,C,T)], SP, ReturnBody ;

ReturnBody = ReturnItems, [SP, Order], [SP, Skip], [SP, Limit] ;

ReturnItems = ('*', { [SP], ',', [SP], ReturnItem })
            | (ReturnItem, { [SP], ',', [SP], ReturnItem })
            ;

ReturnItem = (Expression, SP, (A,S), SP, Binding)
           | Expression
           ;

Order = (O,R,D,E,R), SP, (B,Y), SP, SortItem, { ',', [SP], SortItem } ;

Skip = (S,K,I,P), SP, Expression ;

Limit = (L,I,M,I,T), SP, Expression ;

SortItem = Expression, [[SP], ((A,S,C,E,N,D,I,N,G) | (A,S,C) | (D,E,S,C,E,N,D,I,N,G) | (D,E,S,C))] ;

Where = (W,H,E,R,E), SP, Expression ;

Pattern = PatternPart, { [SP], ',', [SP], PatternPart } ;

PatternPart = (Binding, [SP], '=', [SP], AnonymousPatternPart)
            | AnonymousPatternPart
            ;

AnonymousPatternPart = PatternElement ;

PatternElement = (NodePattern, { [SP], PatternElementChain })
               | ('(', PatternElement, ')')
               ;

NodePattern = '(', [SP], [Binding, [SP]], [NodeLabels, [SP]], [Properties, [SP]], ')' ;

PatternElementChain = RelationshipPattern, [SP], NodePattern ;

RelationshipPattern = (LeftArrowHead, [SP], Dash, [SP], [RelationshipDetail], [SP], Dash, [SP], RightArrowHead)
                    | (LeftArrowHead, [SP], Dash, [SP], [RelationshipDetail], [SP], Dash)
                    | (Dash, [SP], [RelationshipDetail], [SP], Dash, [SP], RightArrowHead)
                    | (Dash, [SP], [RelationshipDetail], [SP], Dash)
                    ;

RelationshipDetail = '[', [SP], [Binding, [SP]], [RelationshipTypes, [SP]], [RangeLiteral], [Properties, [SP]], ']' ;

Properties = MapLiteral (* excluding Parameters as we are not dealing with procedure calls *)
           ;

RelationshipTypes = ':', [SP], RelTypeName, { [SP], '|', [':'], [SP], RelTypeName } ;

NodeLabels = NodeLabel, { [SP], NodeLabel } ;

NodeLabel = ':', [SP], LabelName ;

RangeLiteral = '*', [SP], [IntegerLiteral, [SP]], ['..', [SP], [IntegerLiteral, [SP]]] ;

LabelName = Identifier
          | LabelName, '.', Identifier;

RelTypeName = Identifier ;

Expression = OrExpression ;

OrExpression = XorExpression, { SP, (O,R), SP, XorExpression } ;

XorExpression = AndExpression, { SP, (X,O,R), SP, AndExpression } ;

AndExpression = NotExpression, { SP, (A,N,D), SP, NotExpression } ;

NotExpression = { (N,O,T), [SP] }, ComparisonExpression ;

ComparisonExpression = AddOrSubtractExpression, { [SP], PartialComparisonExpression } ;

AddOrSubtractExpression = MultiplyDivideModuloExpression, { ([SP], '+', [SP], MultiplyDivideModuloExpression) | ([SP], '-', [SP], MultiplyDivideModuloExpression) } ;

MultiplyDivideModuloExpression = PowerOfExpression, { ([SP], '*', [SP], PowerOfExpression) | ([SP], '/', [SP], PowerOfExpression) | ([SP], '%', [SP], PowerOfExpression) } ;

PowerOfExpression = UnaryAddOrSubtractExpression, { [SP], '^', [SP], UnaryAddOrSubtractExpression } ;

UnaryAddOrSubtractExpression = { ('+' | '-'), [SP] }, StringListNullOperatorExpression ;

StringListNullOperatorExpression = PropertyOrLabelsExpression, { ([SP], '[', Expression, ']') | ([SP], '[', [Expression], '..', [Expression], ']') | ((([SP], '=~') | (SP, (I,N)) | (SP, (S,T,A,R,T,S), SP, (W,I,T,H)) | (SP, (E,N,D,S), SP, (W,I,T,H)) | (SP, (C,O,N,T,A,I,N,S))), [SP], PropertyOrLabelsExpression) | (SP, (I,S), SP, (N,U,L,L)) | (SP, (I,S), SP, (N,O,T), SP, (N,U,L,L)) } ;

PropertyOrLabelsExpression = Atom, { [SP], (PropertyLookup | NodeLabels) } ;

MapLiteral = '{', [SP], [PropertyKeyName, [SP], ':', [SP], Expression, [SP], { ',', [SP], PropertyKeyName, [SP], ':', [SP], Expression, [SP] }], '}' ;

Literal = NumberLiteral
        | StringLiteral
        | BooleanLiteral
        | (N,U,L,L)
        | MapLiteral
        | ListLiteral
        ;

Atom = Literal
     | | ((C,O,U,N,T), [SP], '(', [SP], ('*' | NodeLabel), [SP], ')')
     | ParenthesizedExpression
     | Binding
     | BindingWithLiteralType
     ;

BindingWithLiteralType = Binding, [[SP], (':',':'), [SP], BindingType];

BindingType = text
        | int
        | smallint
        | bigint
        | double precision
        | real
        | money
        | bool
        ;

Literal = NumberLiteral
        | StringLiteral
        | BooleanLiteral
        | (N,U,L,L)
        | MapLiteral
        | ListLiteral
        ;

BooleanLiteral = (T,R,U,E)
               | (F,A,L,S,E)
               ;

ListLiteral = '[', [SP], [Expression, [SP], { ',', [SP], Expression, [SP] }], ']' ;

ParenthesizedExpression = '(', [SP], Expression, [SP], ')' ;

PartialComparisonExpression = ('=', [SP], AddOrSubtractExpression)
                            | ('<>', [SP], AddOrSubtractExpression)
                            | ('<', [SP], AddOrSubtractExpression)
                            | ('>', [SP], AddOrSubtractExpression)
                            | ('<=', [SP], AddOrSubtractExpression)
                            | ('>=', [SP], AddOrSubtractExpression)
                            ;

Binding = Identifier;

Identifier = (* any valid symbolic name *)
EOI = (* end of interrupt *);
SP = { whitespace }-; (* any *)

List of Statements (not all included)

Graph

• CREATE GRAPH [ IF NOT EXISTS ] id;
• SET graph_path=id;
• DROP GRAPH id CASCADE;

Labels

// The list of options for labels is longer than that, but I am not including all options as well as constraints and the ALTER stmt

• CREATE ELABEL id [ IF NOT EXISTS ] [ inherits (idSuperELabel1 [ , idSuperELabel2 ] ) ];
• DROP ELABEL id [CASCADE]
• CREATE VLABEL id [ IF NOT EXISTS ] [ inherits (idSuperVLabel) ];
• DROP VLABEL id [CASCADE]

Nodes

([ binding ]:label {property: value, ...})

Relationships

-[[ binding ]:label {property: value, ...}]-

Range

*min..max

Queries

Create

CREATE (node[ [ < ]-relationship-[ > ](node), ... ]);

Match

MATCH (node[ [ < ]-relationship-[ > ](node), ... ]) RETURN binding[[ .property [AS id], ...];

Match by Range

MATCH node[ [ < ]-relationship[ range ]-[ > ](node), ... ] RETURN binding[[ .property [AS id], ...];

Match and Set

MATCH node[ [ < ]-relationship-[ > ](node), ... ] SET binding.property = value;

Match and Delete

MATCH node DETACH DELETE (binding);

Match and Merge

MATCH node MERGE node;
MATCH node RETURN properties(binding);

Transaction

BEGIN;
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
MATCH node
MERGE node;
COMMIT;

ShortestPath

MATCH node[ , ... ] path=shortestpath(node[ [ < ]-relationship-[ > ](node), ... ]) RETURN path;