group_by_source

group_by_source groups a Find* command’s matching objects by the source objects of its relationship lookup. With is_connected_to, each source is an object in the referenced selection. The default is false, which returns objects in one flat array.

group_by_source can also be used in conjunction with Find* commands that use either the image_ref (e.g. FindBoundingBox, FindPolygon) or video_ref (e.g. FindFrame, FindClip) parameter in order to group the results by the source image or video.

group_by_source: true applies at the command level and requires a source reference declared earlier in the transaction. The source command can declare _ref without returning properties. Its uniqueids: true option returns the identifiers that associate group keys with source objects.

For FindConnection, supply src, dst, or both. Groups are keyed by the referenced endpoint objects, and returned values appear under connections. For other Find commands, use a supported relationship selector such as is_connected_to, image_ref, or video_ref. Without a relationship selector, node queries do not create source groups.

Use per_group to apply sorting, offset, and limit independently to each source group. Its default is false: pagination first selects one page across all matches, then places those objects in their source groups. FindClip does not accept per_group. Source grouping cannot be combined with batch.

The entities or connections response becomes an object mapping source _uniqueid strings to arrays. One result can appear under several sources; for metadata results, returned counts distinct objects across the groups. Source keys do not depend on requesting unique IDs for the returned neighbors. With at least one returned object, sources without returned neighbors have empty arrays. When there are no returned objects at all, entities or connections is omitted and returned is 0. Request properties, expressions, or unique IDs to obtain metadata; count alone does not produce a grouped payload.

The current source-grouped response omits results.count and scalar aggregates such as sum and avg. Use a separate ungrouped query for those values. results.group performs property-based aggregation and takes precedence over source grouping; it does not combine both grouping modes.

Examples

The following query finds Person entities connected to people named Jane, Keya, or Stana and groups the matches by those source people. In this case, the first FindEntity returns three matches: “Jane”, “Keya”, and “Stana”. Jane has no matching neighbor, so her unique ID maps to an empty array in the second response. Keya’s array contains “Madhuri”, and Stana’s array contains “Brie” and “Scarlett”. The order of the source keys is not significant.

[{
    "FindEntity": {
        "with_class": "Person",
        "_ref": 1234,
        "uniqueids": true,
        "constraints": [
            "$name",
            "in",
            {
                "array": ["Jane", "Keya", "Stana"]
            }
        ],
        "results": {
            "list": ["name"]
        }
    }
}, {
    "FindEntity": {
        "with_class": "Person",
        "is_connected_to": {
            "ref": 1234,
            "connection_class": "BestFriendForever"
        },
        "group_by_source": true,
        "results": {
            "list": ["name"]
        }
    }
}]

Successful response:

[{
    "FindEntity": {
        "entities": [{
            "_uniqueid": "6.0.59676",
            "name": "Jane"
        }, {
            "_uniqueid": "6.1.59676",
            "name": "Keya"
        }, {
            "_uniqueid": "6.3.59676",
            "name": "Stana"
        }],
        "returned": 3,
        "status": 0
    }
}, {
    "FindEntity": {
        "entities": {
            "6.0.59676": [],
            "6.1.59676": [{
                "name": "Madhuri"
            }],
            "6.3.59676": [{
                "name": "Brie"
            }, {
                "name": "Scarlett"
            }]
        },
        "group_by_source": true,
        "returned": 3,
        "status": 0
    }
}]

Examples​

Examples