Map Projection

cip/1.accepted/CIP2017-02-07-Map-Projection.adoc

@@ -0,0 +1,121 @@
+= CIP2017-02-07 Map Projection
+:numbered:
+:toc:
+:toc-placement: macro
+:source-highlighter: codemirror
+
+*Author:* Tobias Lindaaker <[email protected]>
+
+toc::[]
+
+== Map Projection
+
+Map projection takes a map or entity (node or relationship) and creates a map based on selected properties from map or entity.
+The map projection largely reuses the map syntax of curly braces and comma separated entries.
+But the projection entries are just a single identifier starting with a dot (.).
+The projected map entries use the same key in the projected map as in the source map.
+
+The following example:
+
+[source, cypher]
+----
+someMap {.alpha, .beta}
+----
+
+is thus equivalent to:
+
+[source, cypher]
+----
+{alpha: someMap.alpha, beta: someMap.beta}
+----
+
+In order to be further useful, map projection allow other types of selectors to augment the projected map.
+
+Projected maps are also allowed as a `ReturnItem` in the `RETURN` and `WITH` clauses, in this case the projected map occurs without a preceding variable and instead projects variables from the current scope into a map.
+While both _property selectors_ and _variable selectors_ are syntactically allowed in this case, the semantics of both of these selectors are equivalent.
+
+=== Selectors
+
+There are four different types of entries allowed in a map projection:
+
+• *Property selector* - includes a property from the original map into the projected map using the same key in the projected map as in the original map.
+  This selector optionally also allows further projection of a nested map, if the selected property is a map or entity.
+• *Variable selector* - includes an entry into the projected map based on a variable in the current scope.
+  The key for the entry in the projected map will be the same as the name of the variable.
+  This selector optionally also allows further projection of a nested map, if the selected variable is a map or entity.
+• *Literal entry* - includes a entry into the projected map using the regular map entry syntax, i.e. with the value being explicitly different from the key.
+  In this case the value can be any arbitrary expression, just like in a regular map literal.
+• *All properties selector* - includes all properties from the original map or entity into the projected map. +
+  The all properties selector also allows marking properties for exclusion that would otherwise have been included by the selector. +
+  If any properties explicitly stated in the map projection through another selector type conflicts with a property in the original map, the explicitly stated entry takes precedence and the value from that expression overrides the value from the original map.
+
+Note that while it is typically superfluous to use both an _all properties selector_ and explicit _property selectors_, this is syntactically allowed.
+Sometimes this might be the most convenient way to express the desired projection, since the explicit _property selector_ allows further projection of the nested property, and this value takes precedence over the _all properties selector_.
+
+=== Syntax
+
+The EBNF syntax of map projection takes the following place in the Cypher syntax:
+
+[source, ebnf]
+----
+Atom = … | MapProjection | … ;
+
+MapProjection = Variable, ProjectedMap ;
+
+ProjectedMap = '{', (AllPropertiesSelector | ProjectionEntry), {',', ProjectionEntry}, '}' ;
+
+ProjectionEntry = LiteralEntry
+                | PropertySelector
+                | VariableSelector
+                ;
+LiteralEntry = PropertyKeyName, ':', Expression ;
+PropertySelector = '.', PropertyKeyName, [ProjectedMap] ;
+VariableSelector = Variable, [ProjectedMap] ;
+AllPropertiesSelector = '*', {'-', PropertyKeyName} ;
+
+ReturnItem = Expression
+           | (Expression, 'AS', Variable)
+           | (ProjectedMap, 'AS', Variable)
+           ;
+----
+
+=== Examples
+
+[source, cypher]
+.Fetch name and address for a person
+----
+MATCH (person:Person{userId=$user})-[:ADDRESS]->(address)
+RETURN person {.firstName, .lastName, id: $user,
+               address {.streetAddress, .city, .postalCode} }
+----
+
+.Example result
+----
++----------------------------------------------------------------------------------------+
+| person                                                                                 |
++----------------------------------------------------------------------------------------+
+| {firstName: "Sherlock", lastName: "Holmes", id: "0099CC",                              |
+|  address: {streetAddress: "221B Baker Street", city: "London", postalCode: "NW1 6XE"}} |
++----------------------------------------------------------------------------------------+
+----
+
+[source, cypher]
+.Bind variables into a map
+----
+MATCH (group:Group{name:$groupName})<-[:MEMBER_OF]-(member)-[:KNOWS]-(friend)-[:ADDRESS]->(address)
+RETURN member.name, collect( {friend{.name},address{.city}} ) AS friends
+----
+
+.Example result
+----
++-------------+---------------------------------------------------------------+
+| member.name | friends                                                       |
++-------------+---------------------------------------------------------------+
+| John Doe    | • {friend: {name:"Heather Taylor"}, address:{city:"Miami"}}   |
+|             | • {friend: {name:"Leroy Jenkins"}, address:{city:"New York"}} |
++-------------+---------------------------------------------------------------+
+| Eve Longman | • {friend: {name:"Mickey Mouse"}, address:{city:"Orlando"}}   |
+|             | • {friend: {name:"Leroy Jenkins"}, address:{city:"New York"}} |
+|             | • {friend: {name:"Minnie Mouse"}, address:{city:"Orlando"}}   |
++-------------+---------------------------------------------------------------+
+----