.. _AddEntity: AddEntity ========= Add a new entity of a specified class, and properties associated with the new entity. 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 ` - nonempty string, not starting with underscore - Required. Names the new entity class. * - :ref:`connect ` - connection object or array of connection objects - Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. A customer class is required; direction is in or out (default out); properties sets connection properties. Connections are created only for a newly inserted object. * - :ref:`if_not_found ` - array expression - Optional. Checks existing objects of this exact type/class before insertion. When omitted, no duplicate lookup is performed. A match skips creation, properties, and new connections; status is 2 and _ref names all matches. An empty expression array is invalid. The lookup is restricted to class. * - :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. Details ------- .. include:: add_details.rst Response and errors ------------------- An authenticated session with the objects create permission is required. The response is an object under ``AddEntity`` 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. 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 -------- Add a "Person" using AddEntity command: .. TESTED_EXAMPLE: AddEntity_1 .. code-block:: json [{ "AddEntity": { "class": "Person", "properties": { "name": "Jane Doe", "gender": "F", "email": "jane.doe@xyz.com", "last_connected": 2022 } } }] Successful response: .. TESTED_EXAMPLE: AddEntity_1_response .. code-block:: json [{ "AddEntity": { "status": 0 } }] Conditionally add a "Person" if the email is not already registered: .. TESTED_EXAMPLE: AddEntity_2 .. code-block:: json [{ "AddEntity": { "class": "Person", "if_not_found": ["$email", "==", "jane.doe@xyz.com"], "properties": { "name": "Jane Doe", "gender": "F", "email": "jane.doe@xyz.com", "last_connected": 2022 } } }] Expected response: .. TESTED_EXAMPLE: AddEntity_2_response .. code-block:: json [{ "AddEntity": { "status": 2, "info": "Object Exists!" } }] Conditionally add a "Person" if the email is not already registered, add a "Visit" event, and create a connection between the "Person" and the "Visit": .. TESTED_EXAMPLE: AddEntity_3 .. code-block:: json [{ "AddEntity": { "_ref": 1, "class": "Person", "if_not_found": ["$email", "==", "alice@xyz.com"], "properties": { "name": "Alice", "gender": "F", "email": "alice@xyz.com" } } }, { "AddEntity": { "class": "Visit", "properties": { "start_year": { "_date": "Mon Aug 7 10:59:24 PDT 2017" }, "end_year": { "_date": "Mon Aug 7 12:59:24 PDT 2017" }, "billing_id": 123 }, "connect": { "ref": 1, "class": "PersonMadeVisit" } } }] Successful response: .. TESTED_EXAMPLE: AddEntity_3_response .. code-block:: json [{ "AddEntity": { "status": 0 } }, { "AddEntity": { "status": 0 } }]