## 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"]