AddConnection

Add a connection between two referenced objects, and properties associated with the new connection.

Parameters

Parameter	JSON type	Behavior
_ref	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.
class	nonempty string, not starting with underscore	Required. Names the new connection class.
dst	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.
if_not_found	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.
properties	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.
src	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. 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
    }
}]