FindConnection
Find all connections that satisfy the specified constraints.
Requires an authenticated user with objects.read permission.
Parameters
Parameter |
Type / required |
Default and behavior |
|---|---|---|
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. |
|
expression array / optional |
Omitted: no property filter. Filter graph candidates using the constraint grammar; public system-property access is checked for this command. |
|
integer 1–100000 / optional |
Omitted: no destination endpoint restriction. Refer to objects declared earlier in the same query; with src, both endpoint restrictions apply. |
|
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. |
|
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. |
|
integer 0–2147483647 / optional |
0; skip this many sorted matches, or this many per source group when per_group:true. |
|
boolean / optional |
false; true requires group_by_source:true and applies sorting, offset, and limit separately within each source group. |
|
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. |
|
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. |
|
integer 1–100000 / optional |
Omitted: no source endpoint restriction. Refer to objects declared earlier in the same query; with dst, both endpoint restrictions apply. |
|
boolean / optional |
false; true requires exactly one graph match and returns status 3 if the expectation fails. |
|
boolean / optional |
false; true retains _uniqueid in returned metadata. results.all_properties:true also enables identifiers when uniqueids is omitted. |
|
object / optional |
Filter by the connection name and by the class of either endpoint supplied without a reference. |
|
|
object / optional |
Filter by the object type of either endpoint supplied without a reference. |
string / optional |
Shorthand for a |
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"]
}
}
}]