Skip to main content

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.

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.

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.

with_class

string / optional

Shorthand for a class object with only connection. Supply one class selector.

Use 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 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.

[{
"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.

[{
"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"]
}
}
}]