FindConnection ============== Find all connections that satisfy the specified constraints. Requires an authenticated user with ``objects.read`` permission. Parameters ---------- .. list-table:: :header-rows: 1 :widths: 22 23 55 * - Parameter - Type / required - Default and behavior * - :ref:`_ref ` - integer 1–100000 / optional - Omitted: no caller-visible reference. When supplied, declare a new reference to these matches for later commands in the same query; duplicate declarations are rejected. * - :ref:`constraints ` - expression array / optional - Omitted: no property filter. Filter graph candidates using the constraint grammar; public system-property access is checked for this command. * - :ref:`dst ` - integer 1–100000 / optional - Omitted: no destination endpoint restriction. Refer to objects declared earlier in the same query; with src, both endpoint restrictions apply. * - :ref:`group_by_source ` - boolean / optional - false; true requires src or dst and groups connections by those endpoint objects. With both references, a connection can appear in both endpoint groups. * - :ref:`limit ` - integer 0–2147483647 / optional - Omitted: no explicit match limit. Apply the limit after sorting and offset; per_group:true applies it within each source group. * - :ref:`offset ` - integer 0–2147483647 / optional - 0; skip this many sorted matches, or this many per source group when per_group:true. * - :ref:`per_group ` - boolean / optional - false; true requires group_by_source:true and applies sorting, offset, and limit separately within each source group. * - :ref:`results ` - object / optional - Omitted: no requested user-property projection or aggregate. Select fields, expressions, counts, or aggregates using the results helper; metadata can be omitted if no output fields remain. * - :ref:`sort ` - string, object, or array / optional - Omitted: no explicit property ordering. Accept a property name, a sort object, or an array of either. Expression sorting is incompatible with results.group. * - :ref:`src ` - integer 1–100000 / optional - Omitted: no source endpoint restriction. Refer to objects declared earlier in the same query; with dst, both endpoint restrictions apply. * - :ref:`unique ` - boolean / optional - false; true requires exactly one graph match and returns status 3 if the expectation fails. * - :ref:`uniqueids ` - boolean / optional - false; true retains _uniqueid in returned metadata. results.all_properties:true also enables identifiers when uniqueids is omitted. * - :ref:`class ` - object / optional - Filter by the connection name and by the class of either endpoint supplied without a reference. * - ``target`` - object / optional - Filter by the object type of either endpoint supplied without a reference. * - :ref:`with_class ` - string / optional - Shorthand for a ``class`` object with only ``connection``. Supply one class selector. Use :ref:`text search expressions ` inside constraints for fuzzy or full-text matching, and an explicit sort expression for relevance ordering. A root ``src`` reference selects the source objects. To restrict their class or type, do so in the command that creates the reference and omit ``class.src`` and ``target.src`` here. The same rule applies to ``dst``. If both endpoints use references, you can still filter by the connection name and its properties. Response and recovery --------------------- A successful command returns ``status: 0`` and ``returned``. Requested metadata appears in ``connections``; a reference-only lookup can match objects without returning metadata. ``returned`` counts delivered objects or blobs, not every graph match. Use ``results.count`` to request a match count. Choose at least one of ``_ref``, ``results``, or ``uniqueids: true``. This command consumes and returns no blobs. With ``group_by_source: true``, ``connections`` is grouped by the referenced endpoint objects; ``per_group`` controls sorting and pagination within those groups. Invalid parameters, undeclared or incorrectly typed references, and failed output validation return ``status: -1`` with ``info``. A violated ``unique: true`` expectation returns ``status: 3``. A response that exceeds the configured message budget can return ``status: 4``; reduce the result limit or requested data. See :doc:`../Responses` for error envelopes and retry guidance. Examples -------- Count all ``HasVisited`` connections from ``Patient`` entities to ``Clinic`` entities. The three names in ``class`` and the two types in ``target`` select the connection category directly. .. TESTED_EXAMPLE: FindConnection_1 .. code-block:: json [{ "FindConnection": { "class": { "src": "Patient", "connection": "HasVisited", "dst": "Clinic" }, "target": { "src": "entity", "dst": "entity" }, "results": { "count": true } } }] Count a patient's ``HasVisited`` connections to ``Clinic`` entities and retrieve each visit's ``date`` and ``care_taker``, sorted by date. ``FindEntity`` supplies the source reference and ``FindConnection`` filters the destination. .. TESTED_EXAMPLE: FindConnection_2 .. code-block:: json [{ "FindEntity": { "with_class": "Patient", "_ref": 1, "constraints": ["$patient_id", "==", 231] } }, { "FindConnection": { "src": 1, "class": { "connection": "HasVisited", "dst": "Clinic" }, "target": { "dst": "entity" }, "sort": "date", "results": { "count": true, "list": ["date", "care_taker"] } } }]