group_by_source

When is_connected_to parameter is specified in a Find* command the result is a set of objects connected to the referenced Find* command by connections as defined by the is_connected_to parameter. If only one type of connection is used for traversal, group_by_source offers a way to group the resulting objects by their source entity. This parameter is set to False by default and objects are returned in one flat array. When True and only one connection was used, the results contain a parameter group_by_source as True and the objects are represented by array of arrays as shown in the example below.

Examples

For instance, we can search for entities of class “Person” connected to other entities of class “Person” and with “name” as any of “Jane”, “Keya”, or “Stana”, as follows and return them grouped by their origin entities. In this case, the first FindEntity returns two matches, namely “Keya” and “Stana”. “Madhuri” is returned as the neighbor of the entity with “name” as “Keya” in one array, followed by “Brie” and “Scarlett” which are then returned in another array where they correspond to the source entity with “name” as “Stana”.

[ {
    "FindEntity" : {
        "with_class" : "Person",
        "_ref": 1234,
        "constraints" : {
            "name": ["in", ["Jane", "Keya", "Stana"]]
        },
        "results" : {
            "list": ["name"]
        }
    }
},{
    "FindEntity" : {
        "with_class" : "Person",
        "is_connected_to": {
            "ref": 1234,
            "connection_class": "BestFriendForever",
            "constraints": {
                "since_year": [">=", 2005]
            }
        },
        "group_by_source": true,
        "results" : {
            "list" : [ "name", "age" ]
        }
    }
}]

# Response
[ {
    "FindEntity": {
        "status": 0,
        "returned": 2,
        "entities": [
            {
                "name": "Keya"
            },
            {
                "name": "Stana"
            }
        ]
    }
},{
    "FindEntity": {
        "status": 0,
        "group_by_source": true,
        "returned": 3,
        "entities" : [
            [                           # connected to Keya
                {
                    "name": "Madhuri",
                    "age": 45
                }
            ],
            [                           # connected to "Stana"
                {
                    "name": "Brie",
                    "age": 32
                },
                {
                    "name": "Scarlett",
                    "age": 40
                }
            ]
        ]
    }
}
]