.. _group_by_source: 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 grouping\nand per-group pagination. Without a relationship selector, node queries do not create source groups. Use :ref:`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. .. TESTED_EXAMPLE: group_by_source_1 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: group_by_source_1_response .. code-block:: json [{ "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 } }]