AddConnection ============= Add a connection between two referenced objects, and properties associated with the new connection. Parameters ---------- .. list-table:: :header-rows: 1 :widths: 15 25 60 * - Parameter - JSON type - Behavior * - :ref:`_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. * - :ref:`class ` - string - Required. Names the connection between each pair of referenced objects. * - :ref:`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. * - :ref:`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. * - :ref:`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. * - :ref:`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. :ref:`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: .. TESTED_EXAMPLE: AddConnection_1 .. code-block:: json [{ "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" } } } }] .. TESTED_EXAMPLE: AddConnection_1_response .. code-block:: json [{ "AddEntity": { "status": 0 } }, { "AddEntity": { "status": 0 } }, { "AddConnection": { "status": 0 } }]