AddConnection
Add a connection between two referenced objects, and properties associated with the new connection.
Parameters
Parameter | JSON type | Behavior |
|---|---|---|
integer, 1 through 100000 | Optional. Declares a unique reference for later commands in this transaction. When omitted, no reference is available to later commands. If conditional insertion finds existing objects, the reference names those matches. | |
string | Required. Names the connection between each pair of referenced objects. | |
integer, 1 through 100000 | Required. Uses an earlier compatible node reference in this transaction; forward references, wrong types, and undeclared references are rejected. Every source/destination pair receives a connection; an empty endpoint set creates none. | |
array expression | Optional. Checks existing connections of this class separately for each source/destination pair. When omitted, no duplicate lookup is performed. Matching pairs are skipped; other pairs are created. _ref includes both existing matches and new connections. Status is 2 only when every pair was already present. | |
object mapping property names to values | Optional. When omitted, no user properties are added. Stores booleans, numbers, strings, supported arrays, or single-key _date, _blob, and _json wrappers. Bare null is rejected; property names and wrapped values are validated. See the properties reference for nested value rules. | |
integer, 1 through 100000 | Required. Uses an earlier compatible node reference in this transaction; forward references, wrong types, and undeclared references are rejected. Every source/destination pair receives a connection; an empty endpoint set creates none. |
Details
The source and destination references (src and dst) identify objects created or found by earlier commands in the transaction. Each pair of objects determines its source and destination classes and types. properties stores key-value pairs on the new connection.
Response and errors
An authenticated session with the objects create permission is required.
The response is an object under AddConnection with integer status. Status 0 means creation succeeded; status 2 means conditional insertion found existing objects. No output blob or created-object count is returned. Status 1 means one or both endpoint references contain no nodes, so no connection was created.
Invalid field types, missing required fields, malformed expressions, and invalid references fail validation. Execution failures include a nonzero status and an info message; inspect the transaction response before assuming a mutation succeeded.
Examples
The following request adds two Person entities and creates a connection between them:
[{
"AddEntity": {
"class": "Person",
"_ref": 1,
"properties": {
"name": "Jane Polansky",
"gender": "F",
"email": "jane.p@xyz.com"
}
}
}, {
"AddEntity": {
"class": "Person",
"_ref": 2,
"properties": {
"name": "Jon Doe",
"gender": "M",
"email": "jon.doe@xyz.com"
}
}
}, {
"AddConnection": {
"class": "BestFriendsForever",
"src": 1,
"dst": 2,
"properties": {
"place_met": "Fake Street 123",
"date": {
"_date": "Mon Apr 10 10:59:24 PDT 1970"
}
}
}
}]
[{
"AddEntity": {
"status": 0
}
}, {
"AddEntity": {
"status": 0
}
}, {
"AddConnection": {
"status": 0
}
}]