9.2. Map Functions

This section describes functions for working with maps.

apoc.map.flatten(map,delimiter:".")

flatten a nested map into a single-level map, for example turning {parent:{child:1}} into {"parent.child":1}

apoc.map.fromNodes(label, property)

creates map from nodes with this label grouped by property

apoc.map.fromPairs([[key,value],[key2,value2],…​])

creates map from list with key-value pairs

apoc.map.fromLists([keys],[values])

creates map from a keys and a values list

apoc.map.fromValues([key,value,key1,value1])

creates map from alternating keys and values in a list

apoc.map.merge({first},{second}) yield value

creates map from merging the two source maps

apoc.map.mergeList([{maps}]) yield value

merges all maps in the list into one

apoc.map.setKey(map,key,value)

returns the map with the value for this key added or replaced

apoc.map.removeKey(map,key,{recursive:true/false})

returns the map with the key removed (recursively if recursive is true)

apoc.map.removeKeys(map,[keys],{recursive:true/false})

returns the map with the keys removed (recursively if recursive is true)

apoc.map.clean(map,[keys],[values]) yield value

removes the keys and values (e.g. null-placeholders) contained in those lists, good for data cleaning from CSV/JSON

apoc.map.groupBy([maps/nodes/relationships],'key') yield value

creates a map of the list keyed by the given property, with single values

apoc.map.groupByMulti([maps/nodes/relationships],'key') yield value

creates a map of the list keyed by the given property, with list values

apoc.map.sortedProperties(map, ignoreCase:true)

returns a list of key/value list pairs, with pairs sorted by keys alphabetically, with optional case sensitivity

apoc.map.updateTree(tree,key,)

returns map - adds the {data} map on each level of the nested tree, where the key-value pairs match

apoc.map.values(map, [key1,key2,key3,…​],[addNullsForMissing])

returns list of values indicated by the keys

apoc.map.submap(map,keys,,[fail=true])

returns submap for keys or throws exception if one of the key doesn’t exist and no default value given at that position

apoc.map.mget(map,keys,,[fail=true])

returns list of values for keys or throws exception if one of the key doesn’t exist and no default value given at that position

apoc.map.get(map,key,[default],[fail=true])

returns value for key or throws exception if key doesn’t exist and no default given

The following creates a map from list of key-value pairs: 

RETURN apoc.map.fromPairs([
    ["name", "Cristiano Ronaldo"],
    ["age", date("1985-02-05")]
]) AS output

Table 9.8. Results
Output
{
  "name": "Cristiano Ronaldo",
  "age": "1985-02-05"
}

The following creates a map from alternating keys and values in a list: 

RETURN apoc.map.fromValues([
    "name", "Cristiano Ronaldo",
    "age", date("1985-02-05")
]) AS output

Table 9.9. Results
Output
{
  "name": "Cristiano Ronaldo",
  "age": "1985-02-05"
}

The following creates a map from keys and values lists: 

RETURN apoc.map.fromLists(
    ["name", "dob"],
    ["Cristiano Ronaldo", date("1985-02-05")]
) AS output

Table 9.10. Results
Output
{
  "name": "Cristiano Ronaldo",
  "age": "1985-02-05"
}

The following merges two maps: 

RETURN apoc.map.merge(
    {name: "Cristiano Ronaldo", dob: date("1985-02-05")},
    {country: "Portugal"}
) AS output

Table 9.11. Results
Output
{
  "name": "Cristiano Ronaldo",
  "country": "Portugal",
  "dob": "1985-02-05"
}

The following merges multiple maps: 

RETURN apoc.map.mergeList([
    {name: "Cristiano Ronaldo"},
    {dob: date("1985-02-05")},
    {country: "Portugal"}
]) AS output

Table 9.12. Results
Output
{
  "name": "Cristiano Ronaldo",
  "country": "Portugal",
  "dob": "1985-02-05"
}

The following updates a key in a map: 

RETURN apoc.map.setKey(
    {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")},
    "dob",
    date("1986-02-06")
) AS output

Table 9.13. Results
Output
{
  "name": "Cristiano Ronaldo",
  "country": "Portugal",
  "dob": "1986-02-06"
}

The following removes a key from a map: 

RETURN apoc.map.removeKey(
    {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")},
    "dob"
) AS output

Table 9.14. Results
Output
{
  "name": "Cristiano Ronaldo",
  "country": "Portugal"
}

The following removes keys from a map: 

RETURN apoc.map.removeKeys(
    {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")},
    ["dob", "country"]
) AS output

Table 9.15. Results
Output
{
  "name": "Cristiano Ronaldo"
}

The following removes empty string values from a map: 

RETURN apoc.map.clean({name: "Cristiano Ronaldo", club: ""}, [], [""]) AS output

Table 9.16. Results
Output
{
  "name": "Cristiano Ronaldo"
}

The following removes empty string values and the keys dob and country from a map: 

RETURN apoc.map.clean(
    {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05"), club: ""},
    ["dob", "country"],
    [""]
) AS output

Table 9.17. Results
Output
{
  "name": "Cristiano Ronaldo"
}

The following returns a list of key/value list pairs with pairs sorted by key alphabetically: 

WITH {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")} AS map
RETURN apoc.map.sortedProperties(map) AS output

Table 9.18. Results
Output

[["country","Portugal"],["dob","1985-02-05"],["name","Cristiano Ronaldo"]]

The following creates a map keyed by club, with list values. 

RETURN apoc.map.groupByMulti([
	{name: "Cristiano Ronaldo", club: "Juventus"},
    {name: "Lionel Messi", club: "Barcelona"},
    {name: "Aaron Ramsey", club: "Juventus"},
    {name: "Luiz Suarez", club: "Barcelona"}
], "club") AS output

Table 9.19. Results
Output
{
    "Juventus": [
      {
        "name": "Cristiano Ronaldo",
        "club": "Juventus"
      },
      {
        "name": "Aaron Ramsey",
        "club": "Juventus"
      }
    ],
    "Barcelona": [
      {
        "name": "Lionel Messi",
        "club": "Barcelona"
      },
      {
        "name": "Luiz Suarez",
        "club": "Barcelona"
      }
    ]
  }

The following returns a list of values for keys name and country, and a null value for missing key missingKey

WITH {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")} AS map
RETURN apoc.map.values(map, ["name", "country", "missingKey"], true) AS output

Table 9.20. Results
Output

["Cristiano Ronaldo","Portugal",null]

The following throws an exception when attempting to look up missing key missingKey with no default value: 

WITH {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")} AS map
RETURN apoc.map.get(map, "missingKey") AS output

Table 9.21. Results
Output

Neo.ClientError.Procedure.ProcedureCallFailed: Failed to invoke function apoc.map.get: Caused by: java.lang.IllegalArgumentException: Key missingKey is not of one of the existing keys [country, dob, name]

The following returns default value defaultValue when attempting to look up missing key missingKey

WITH {name:"Cristiano Ronaldo", country:"Portugal", dob:date("1985-02-05")} AS map
RETURN apoc.map.get(map, "missingKey", "defaultValue") AS output

Table 9.22. Results
Output

"defaultValue"

The following returns a list of values for keys name and country

WITH {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")} AS map
RETURN apoc.map.mget(map, ["name", "country"]) AS output

Table 9.23. Results
Output

["Cristiano Ronaldo", "Portugal"]

The following returns a list of values for keys name and country, and default value defaultValue for missing key missingKey

WITH {name:"Cristiano Ronaldo",country:"Portugal",dob:date("1985-02-05")} AS map
RETURN apoc.map.mget(
    map,
    ["name", "country", "missingKey"],
    [null, null, "defaultValue"]
) AS output

Table 9.24. Results
Output

["Cristiano Ronaldo", "Portugal", "defaultValue"]