FindConnection

Find all connections that satisfy the specified constraints.

Requires an authenticated user with objects.read permission.

Parameters

Parameter	Type / required	Default and behavior
_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. Incompatible with batch.
batch	object / optional	Omitted: no distributed result batching. Partition a cached query result using the batch helper; incompatible with _ref and group_by_source:true.
constraints	expression array / optional	Omitted: no property filter. Filter graph candidates using the constraint grammar; public system-property access is checked for this command.
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.
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.
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.
offset	integer 0–2147483647 / optional	0; skip this many sorted matches, or this many per source group when per_group:true.
per_group	boolean / optional	false; true requires group_by_source:true and applies sorting, offset, and limit separately within each source group.
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.
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.
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.
unique	boolean / optional	false; true requires exactly one graph match and returns status 3 if the expectation fails.
uniqueids	boolean / optional	false; true retains _uniqueid in returned metadata. results.all_properties:true also enables identifiers when uniqueids is omitted.
with_class	string / optional	Omitted: search all connection classes. If supplied, the class must be nonempty and must not begin with an underscore.

Use text search expressions inside constraints for fuzzy or full-text matching, and an explicit sort expression for relevance ordering.

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 Responses for error envelopes and retry guidance.

Examples

Count the number of connections of class “HasVisited”:

[{
    "FindConnection": {
        "with_class": "HasVisited",
        "results": {
            "count": true
        }
    }
}]

Count the number of connections of class “HasVisited” that an Entity of the class “Patient” has, where the Entity of class “Patient” is the source of the Connection, and retrieve the “date” and “care_taker” properties of the Connection. Sort the results by date:

[{
    "FindEntity": {
        "with_class": "Patient",
        "_ref": 1,
        "constraints": ["$patient_id", "==", 231]
    }
}, {
    "FindConnection": {
        "with_class": "HasVisited",
        "src": 1,
        "sort": "date",
        "results": {
            "count": true,
            "list": ["date", "care_taker"]
        }
    }
}]