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

string

Required. Names the connection between each pair of referenced objects.

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. 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
    }
}]