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. The reverse owner selectors bounding_box_ref,n``polygon_ref``, frame_ref and clip_ref also support source groupingnand per-group pagination. 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.
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": [{
"_class": "Person",
"_uniqueid": "6.0.59676",
"name": "Jane"
}, {
"_class": "Person",
"_uniqueid": "6.1.59676",
"name": "Keya"
}, {
"_class": "Person",
"_uniqueid": "6.3.59676",
"name": "Stana"
}],
"returned": 3,
"status": 0
}
}, {
"FindEntity": {
"entities": {
"6.0.59676": [],
"6.1.59676": [{
"_class": "Person",
"name": "Madhuri"
}],
"6.3.59676": [{
"_class": "Person",
"name": "Brie"
}, {
"_class": "Person",
"name": "Scarlett"
}]
},
"group_by_source": true,
"returned": 3,
"status": 0
}
}]