Updates existing Entity(ies) or adds new one when not found.

The local id allows an application to chain this command with following operations or associate with a previous search.


  • [optional] class: name of entity class.
  • [optional] _ref: reference to be used within the transaction.



This command provides ways to find one or more existing entities and then lets an application add, change or remove properties.

Either _ref OR [class and/or constraints] must be specified.

If the _ref parameter is specified, it must refers to the search results of a previous FindEntity or AddEntity.

The call can result in an update to multiple entities depending on the search criteria. Unique is not assumed to be true in this case.

If search result is empty, this command will Add a new entity object. The “remove_props” block is ignored in this case.


Add an entity of the class “Person” is there is no other Entity of the same class with the “unique_id” property equals to 431:

[ {
    "UpsertEntity" : {
        "class": "Person",
        "constraints": {
            "unique_id": ["==", 431],
        "properties" : {
            "name" : "John Bonachon",
            "unique_id" : 431