apoc.convert.toTree

Procedure APOC Core

apoc.convert.toTree([paths],[lowerCaseRels=true], [config]) creates a stream of nested documents representing the at least one root of these paths

Signature

apoc.convert.toTree(paths :: LIST? OF PATH?, lowerCaseRels = true :: BOOLEAN?, config = {} :: MAP?) :: (value :: MAP?)

Input parameters

Name Type Default

paths

LIST? OF PATH?

null

lowerCaseRels

BOOLEAN?

true

config

MAP?

{}

Config parameters

The procedure support the following config parameters:

Table 1. Config parameters
name type default description

nodes

Map<String, List<String>>

{}

properties to include for each node label e.g. {Movie: ['title']} or to exclude (e.g. {Movie: ['-title']}).

rels

Map<String, List<String>>

{}

properties to include for each relationship type e.g. {`ACTED_IN: ["roles"]}` or to exclude (e.g. {`ACTED_IN: ["-roles"]}`).

sortPaths

boolean

true

to sort the result by path length

Output parameters

Name Type

value

MAP?

Usage Examples

The examples in this section are based on the following sample graph:

CREATE (Keanu:Person {name:'Keanu Reeves', born:1964})
CREATE (TomH:Person {name:'Tom Hanks', born:1956})
CREATE (TomT:Person {name:'Tom Tykwer', born:1965})
CREATE (JamesThompson:Person {name:'James Thompson'})

CREATE (TheMatrix:Movie {title:'The Matrix', released:1999, tagline:'Welcome to the Real World'})
CREATE (TheMatrixReloaded:Movie {title:'The Matrix Reloaded', released:2003, tagline:'Free your mind'})
CREATE (TheMatrixRevolutions:Movie {title:'The Matrix Revolutions', released:2003, tagline:'Everything that has a beginning has an end'})
CREATE (SomethingsGottaGive:Movie {title:"Something's Gotta Give", released:2003})
CREATE (TheDevilsAdvocate:Movie {title:"The Devil's Advocate", released:1997, tagline:'Evil has its winning ways'})

CREATE (YouveGotMail:Movie {title:"You've Got Mail", released:1998, tagline:'At odds in life... in love on-line.'})
CREATE (SleeplessInSeattle:Movie {title:'Sleepless in Seattle', released:1993, tagline:'What if someone you never met, someone you never saw, someone you never knew was the only someone for you?'})
CREATE (ThatThingYouDo:Movie {title:'That Thing You Do', released:1996, tagline:'In every life there comes a time when that thing you dream becomes that thing you do'})
CREATE (CloudAtlas:Movie {title:'Cloud Atlas', released:2012, tagline:'Everything is connected'})

CREATE (Keanu)-[:ACTED_IN {roles:['Neo']}]->(TheMatrix)
CREATE (Keanu)-[:ACTED_IN {roles:['Neo']}]->(TheMatrixReloaded)
CREATE (Keanu)-[:ACTED_IN {roles:['Neo']}]->(TheMatrixRevolutions)
CREATE (Keanu)-[:ACTED_IN {roles:['Julian Mercer']}]->(SomethingsGottaGive)
CREATE (Keanu)-[:ACTED_IN {roles:['Kevin Lomax']}]->(TheDevilsAdvocate)

CREATE (TomH)-[:ACTED_IN {roles:['Joe Fox']}]->(YouveGotMail)
CREATE (TomH)-[:ACTED_IN {roles:['Sam Baldwin']}]->(SleeplessInSeattle)
CREATE (TomH)-[:ACTED_IN {roles:['Mr. White']}]->(ThatThingYouDo)
CREATE (TomH)-[:ACTED_IN {roles:['Zachry', 'Dr. Henry Goose', 'Isaac Sachs', 'Dermot Hoggins']}]->(CloudAtlas)
CREATE (TomT)-[:DIRECTED]->(CloudAtlas)

CREATE (JamesThompson)-[:REVIEWED {summary:'Enjoyed it!', rating:95}]->(TheMatrix)
CREATE (JamesThompson)-[:REVIEWED {summary:'It was alright.', rating:65}]->(TheMatrixReloaded)
CREATE (JamesThompson)-[:REVIEWED {summary:'The best of the three', rating:100}]->(TheMatrixRevolutions);

The following converts a list of paths of Keanu Reeves movies into a nested map:

MATCH path = (p:Person {name: "Keanu Reeves"})-[:ACTED_IN]->(movie)
WITH collect(path) AS paths
CALL apoc.convert.toTree(paths)
YIELD value
RETURN value;
Table 2. Results
value 
{
   "_type":"Person",
   "name":"Keanu Reeves",
   "acted_in":[
      {
         "acted_in.roles":[
            "Kevin Lomax"
         ],
         "_type":"Movie",
         "tagline":"Evil has its winning ways",
         "_id":34,
         "title":"The Devil's Advocate",
         "released":1997
      },
      {
         "_type":"Movie",
         "_id":33,
         "title":"Something's Gotta Give",
         "acted_in.roles":[
            "Julian Mercer"
         ],
         "released":2003
      },
      {
         "acted_in.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Everything that has a beginning has an end",
         "_id":32,
         "title":"The Matrix Revolutions",
         "released":2003
      },
      {
         "acted_in.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Free your mind",
         "_id":31,
         "title":"The Matrix Reloaded",
         "released":2003
      },
      {
         "acted_in.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Welcome to the Real World",
         "_id":30,
         "title":"The Matrix",
         "released":1999
      }
   ],
   "_id":27,
   "born":1964
}

By default, relationship types are converted to lower case. We can keep their normal casing by passing in false for the 2nd parameter (lowerCaseRels):

MATCH path = (p:Person {name: "Keanu Reeves"})-[:ACTED_IN]->(movie)
WITH collect(path) AS paths
CALL apoc.convert.toTree(paths, false)
YIELD value
RETURN value;
Table 3. Results
value 
{
   "_type":"Person",
   "name":"Keanu Reeves",
   "ACTED_IN":[
      {
         "ACTED_IN.roles":[
            "Kevin Lomax"
         ],
         "_type":"Movie",
         "tagline":"Evil has its winning ways",
         "_id":34,
         "title":"The Devil's Advocate",
         "released":1997
      },
      {
         "_type":"Movie",
         "_id":33,
         "title":"Something's Gotta Give",
         "released":2003,
         "ACTED_IN.roles":[
            "Julian Mercer"
         ]
      },
      {
         "ACTED_IN.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Everything that has a beginning has an end",
         "_id":32,
         "title":"The Matrix Revolutions",
         "released":2003
      },
      {
         "ACTED_IN.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Free your mind",
         "_id":31,
         "title":"The Matrix Reloaded",
         "released":2003
      },
      {
         "ACTED_IN.roles":[
            "Neo"
         ],
         "_type":"Movie",
         "tagline":"Welcome to the Real World",
         "_id":30,
         "title":"The Matrix",
         "released":1999
      }
   ],
   "_id":27,
   "born":1964
}

By default, all properties are included for node labels and relationship types. We can limit the properties for nodes using the nodes config key and for relationship types using the rels config key.

If we want to return only the title of each of Keanu Reeves' movies, we can do this using the following query:

MATCH path = (p:Person {name: "Keanu Reeves"})-[:ACTED_IN]->(movie)
WITH collect(path) AS paths
CALL apoc.convert.toTree(paths, true, {
  nodes: {Movie: ['title']}
})
YIELD value
RETURN value;
Table 4. Results
value 
{
   "_type":"Person",
   "name":"Keanu Reeves",
   "acted_in":[
      {
         "_type":"Movie",
         "_id":34,
         "title":"The Devil's Advocate",
         "acted_in.roles":[
            "Kevin Lomax"
         ]
      },
      {
         "_type":"Movie",
         "_id":33,
         "title":"Something's Gotta Give",
         "acted_in.roles":[
            "Julian Mercer"
         ]
      },
      {
         "_type":"Movie",
         "_id":32,
         "title":"The Matrix Revolutions",
         "acted_in.roles":[
            "Neo"
         ]
      },
      {
         "_type":"Movie",
         "_id":31,
         "title":"The Matrix Reloaded",
         "acted_in.roles":[
            "Neo"
         ]
      },
      {
         "_type":"Movie",
         "_id":30,
         "title":"The Matrix",
         "acted_in.roles":[
            "Neo"
         ]
      }
   ],
   "_id":27,
   "born":1964
}

And if we want to return only the rating of movies reviewed by James Thompson, we can do this using the following query:

MATCH path = (p:Person {name:'James Thompson'})-[:REVIEWED]->(movie)
WITH collect(path) AS paths
CALL apoc.convert.toTree(paths, true, {
  nodes: {Movie: ['title']},
  rels:  {reviewed: ['rating']}
})
YIELD value
RETURN value;
Table 5. Results
value 
{
   "_type":"Person",
   "name":"James Thompson",
   "reviewed":[
      {
         "_type":"Movie",
         "_id":43,
         "reviewed.rating":95,
         "title":"The Matrix"
      },
      {
         "_type":"Movie",
         "_id":45,
         "reviewed.rating":100,
         "title":"The Matrix Revolutions"
      },
      {
         "_type":"Movie",
         "_id":44,
         "reviewed.rating":65,
         "title":"The Matrix Reloaded"
      }
   ],
   "_id":42
}

On the other hand, we can also include everything and specify certain nodes/relationships to exclude. For example:

MATCH path = (p:Person {name:'James Thompson'})-[:REVIEWED]->(movie)
WITH collect(path) AS paths
CALL apoc.convert.toTree(paths, true, {
  nodes: {Movie: ['-title']},
  rels:  {reviewed: ['-rating']}
})
YIELD value
RETURN value;
Table 6. Results
value 
{
  "_type": "Person",
  "name": "James Thompson",
  "reviewed": [
    {
      "_type": "Movie",
      "tagline": "Everything that has a beginning has an end",
      "reviewed.summary": "The best of the three",
      "_id": 6,
      "released": 2003
    },
    {
      "_type": "Movie",
      "tagline": "Free your mind",
      "reviewed.summary": "It was alright.",
      "_id": 5,
      "released": 2003
    },
    {
      "_type": "Movie",
      "tagline": "Welcome to the Real World",
      "reviewed.summary": "Enjoyed it!",
      "_id": 4,
      "released": 1999
    }
  ],
  "_id": 3
}