Maps

The following graph is used for the examples below:

Graph
  N0 [
    label = "{Person|name = \'Charlie Sheen\'\lrealName = \'Carlos Irwin Estévez\'\l}"
  ]
  N0 -> N4 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N0 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N1 [
    label = "{Person|name = \'Martin Sheen\'\l}"
  ]
  N1 -> N4 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N1 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "ACTED_IN\n"
  ]
  N2 [
    label = "{Movie|year = 1987\ltitle = \'Wall Street\'\l}"
  ]
  N3 [
    label = "{Movie|year = 1984\ltitle = \'Red Dawn\'\l}"
  ]
  N4 [
    label = "{Movie|year = 1979\ltitle = \'Apocalypse Now\'\l}"
  ]

Information regarding property access operators such as . and [] can be found here. The behavior of the [] operator with respect to null is detailed here.

Literal maps

Cypher® supports construction of maps. The key names in a map must be of type String. If returned through an HTTP API call, a JSON object will be returned. If returned in Java, an object of type java.util.Map<String,Object> will be returned.

Query
RETURN { key: 'Value', listKey: [{ inner: 'Map1' }, { inner: 'Map2' }]}
Table 1. Result
{ key: 'Value', listKey: [{ inner: 'Map1' }, { inner: 'Map2' }]}

{listKey -> [{inner -> "Map1"},{inner -> "Map2"}], key -> "Value"}

1 row

Map projection

Cypher supports a concept called "map projections". It allows for easily constructing map projections from nodes, relationships and other map values.

A map projection begins with the variable bound to the graph entity to be projected from, and contains a body of comma-separated map elements, enclosed by { and }.

map_variable {map_element, [, …​n]}

A map element projects one or more key-value pairs to the map projection. There exist four different types of map projection elements:

  • Property selector - Projects the property name as the key, and the value from the map_variable as the value for the projection.

  • Literal entry - This is a key-value pair, with the value being arbitrary expression key: <expression>.

  • Variable selector - Projects a variable, with the variable name as the key, and the value the variable is pointing to as the value of the projection. Its syntax is just the variable.

  • All-properties selector - projects all key-value pairs from the map_variable value.

The following conditions apply:

  • If the map_variable points to a null value, the whole map projection will evaluate to null.

  • The key names in a map must be of type String.

Examples of map projections

Find 'Charlie Sheen' and return data about him and the movies he has acted in. This example shows an example of map projection with a literal entry, which in turn also uses map projection inside the aggregating collect().

Query
MATCH (actor:Person { name: 'Charlie Sheen' })-[:ACTED_IN]->(movie:Movie)
RETURN actor { .name, .realName, movies: collect(movie { .title, .year })}
Table 2. Result
actor

{movies -> [{year -> 1979, title -> "Apocalypse Now"},{year -> 1984, title -> "Red Dawn"},{year -> 1987, title -> "Wall Street"}], realName -> "Carlos Irwin Estévez", name -> "Charlie Sheen"}

1 row

Find all persons that have acted in movies, and show number for each. This example introduces an variable with the count, and uses a variable selector to project the value.

Query
MATCH (actor:Person)-[:ACTED_IN]->(movie:Movie)
WITH actor, count(movie) AS nrOfMovies
RETURN actor { .name, nrOfMovies }
Table 3. Result
actor

{nrOfMovies -> 3, name -> "Charlie Sheen"}

{nrOfMovies -> 2, name -> "Martin Sheen"}

2 rows

Again, focusing on 'Charlie Sheen', this time returning all properties from the node. Here we use an all-properties selector to project all the node properties, and additionally, explicitly project the property age. Since this property does not exist on the node, a null value is projected instead.

Query
MATCH (actor:Person { name: 'Charlie Sheen' })
RETURN actor { .*, .age }
Table 4. Result
actor

{realName -> "Carlos Irwin Estévez", name -> "Charlie Sheen", age -> <null>}

1 row