Skip to content

Adding to a relation

This operation adds child objects to a parent in a relationship. Unlike the Setting a relation operation, which removes any existing child objects and sets the provided children, this operation adds the children to the existing ones.

There are multiple "flavors" of this operation, but in its core, it must reference a parent object and one or more child objects. The parent object must have a valid objectId value. The APIs are grouped below by how the child objects are identified - using objectId, with a query or as a result of a previous operation in the same transaction:

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "ADD_RELATION",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
         "parentObject" : "objectId value" | OPRESULT-REFERENCE-OBJECT,
         "relationColumn" : "column name",
         "unconditional" : [ "objectId VALUE", "objectId VALUE", "objectId VALUE" ]
      }
    }
  ]
}

where:

Argument                Description
"operationType" The value must be "ADD_RELATION" , this designates the operation as "adding child objects to an existing set of children of the parent object for a relation". The objects to add as children for the parent are defined in the "payload" > "unconditional" property.
"table" The value must contain the name of the table where the parent object is stored.
"opResultId" This is an optional property. If present, must contain an Id for this operation. An operation Id is a free-form string that must be unique within the transaction. If the result of this operation is to be used as an input in another operation within the same transaction, the Id will be used to reference the result.
"payload" > "parentObject" The value is mandatory. Must contain either parent's object objectId property or a JSON object identifying a previous operation's result. If an explicit objectId value is used for the parent object, the object must be stored in a table identified by the "table" property. If the parent object is referenced through a result of a previous operation, it must have the following format:
{
"___ref" : true,
"opResultId" : "VALUE",
"resultIndex" : VALUE,
"propName" : "objectId"
}
If a previous operation is Retrieving objects , the "payload" > "parentObject" must contain values for the "opResultId" , "resultIndex" and "propName" properties:
 
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "RETRIEVING-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE,
    "propName": "objectId"
  },
  ...
  ...
}


If a operation is Saving multiple objects , the "payload" > "parentObject" must contain values for the "opResultId" , and "resultIndex" properties:

"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-MULTIPLE-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE
  },
  ...
  ...
}

If a operation is Saving single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

If a operation is Updating single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "UPDATING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

For more information see the Operation Result chapter of this guide.
For more information see the Operation Result chapter of this guide. | | "payload" > "columnName" | The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are added to the parent object. The column must be declared in the same table where the parent object is stored, that is the table identified by the "table" property. | | "payload" > "unconditional" | The value is mandatory. Must contain a JSON array. The array contains objectId values identifying the objects which will be added as child objects for the relationship identified by the "columnName" column. The child objects must be stored in the child table which the "columnName" column points to. |

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "ADD_RELATION",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
         "parentObject" : "objectId value" | OPRESULT-REFERENCE-OBJECT,
         "relationColumn" : "column name",
         "conditional" : "where clause to identify the child objects"
      }
    }
  ]
}

where:

Argument                Description
"operationType" The value must be "ADD_RELATION" , this designates the operation as "adding child objects to an existing set of children of the parent object for a relation". The objects to add as children for the parent are defined in the "payload" > "conditional" property through a query.
"table" The value must contain the name of the table where the objects will be deleted.
"opResultId" This is an optional property. If present, must contain an Id for this operation. An operation Id is a free-form string that must be unique within the transaction. If the result of this operation is to be used as an input in another operation within the same transaction, the Id will be used to reference the result.
"payload" > "parentObject" The value is mandatory. Must contain either a value of the parent's object objectId property or a JSON object identifying a reference to the result from a previous operation. If objectId is used, the object must be stored in the table identified by the "table" property. If the parent object is identified in a result of a previous operation, it must have the following format:
{
"___ref" : true,
"opResultId" : "VALUE",
"resultIndex" : VALUE,
"propName" : "objectId"
}
If a previous operation is Retrieving objects , the "payload" > "parentObject" must contain values for the "opResultId" , "resultIndex" and "propName" properties:
 
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "RETRIEVING-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE,
    "propName": "objectId"
  },
  ...
  ...
}


If a operation is Saving multiple objects , the "payload" > "parentObject" must contain values for the "opResultId" , and "resultIndex" properties:

"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-MULTIPLE-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE
  },
  ...
  ...
}

If a operation is Saving single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

If a operation is Updating single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "UPDATING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

For more information see the Operation Result chapter of this guide.
For more information see the Operation Result chapter of this guide. | | "payload" > "columnName" | The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are added to the parent object. The column must be declared in the same table where the parent object is stored, that is the table identified by the "table" property. | | "payload" > "conditional" | The value is mandatory. Must contain a where clause query. Backendless uses the query to identify the objects in the child table which the "columnName" column points to. The objects which match the query will be added as children to the parent object for the "columnName" relation. |

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "ADD_RELATION",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
         "parentObject" : "objectId value" | OPRESULT-REFERENCE-OBJECT,
         "relationColumn" : "column name",
         "unconditional" : {
             "___ref": true,
             "opResultId" : "VALUE"
         }
      }
    }
  ]
}

where:

Argument                Description
"operationType" The value must be "ADD_RELATION" , this designates the operation as "adding child objects to an existing set of children of the parent object for a relation". The objects to add as children for the parent are defined in the "payload" > "unconditional" property.
"table" The value must contain the name of the table where the objects will be deleted.
"opResultId" This is an optional property. If present, must contain an Id for this operation. An operation Id is a free-form string that must be unique within the transaction. If the result of this operation is to be used as an input in another operation within the same transaction, the Id will be used to reference the result.
"payload" > "parentObject" The value is mandatory. Must contain either a value of the parent's object objectId property or a JSON object identifying a reference to the result from a previous operation. If objectId is used, the object must be stored in the table identified by the "table" property. If the parent object is identified in a result of a previous operation, it must have the following format:
{
"___ref" : true,
"opResultId" : "VALUE",
"resultIndex" : VALUE,
"propName" : "objectId"
}
If a previous operation is Retrieving objects , the "payload" > "parentObject" must contain values for the "opResultId" , "resultIndex" and "propName" properties:
 
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "RETRIEVING-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE,
    "propName": "objectId"
  },
  ...
  ...
}


If a operation is Saving multiple objects , the "payload" > "parentObject" must contain values for the "opResultId" , and "resultIndex" properties:

"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-MULTIPLE-OBJECTS-OPRESULT-ID",
    "resultIndex": VALUE
  },
  ...
  ...
}

If a operation is Saving single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "SAVING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

If a operation is Updating single object , the "payload" > "parentObject" must contain value only for the "opResultId" property:
"payload": {
  "parentObject" : {
    ___ref": true,
    "opResultId": "UPDATING-SINGLE-OBJECT-OPRESULT-ID"
  },
  ...
  ...
}

For more information see the Operation Result chapter of this guide.
For more information see the Operation Result chapter of this guide. | | "payload" > "columnName" | The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are added to the parent object. The column must be declared in the same table where the parent object is stored, that is the table identified by the "table" property. | | "payload" > "unconditional" | The value is mandatory. Must contain a JSON object with the format shown above. This operation expects a collection of child objects. This means the referenced operation result is one that is returned by either the Retrieving objects or the Saving multiple objects operations. |

Return Value

This operation returns the number of objects added in the relation. The returned value can be used in other operations of the same transaction.

Examples

The examples below are grouped by the criteria of how the child objects are identified:

Request:

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "operations": [
     {
      "operationType": "ADD_RELATION",
      "table": "Person",
      "payload": {
        "parentObject" : "E7AD83E0-1B4E-D250-FF46-61BFAB18D700",
        "relationColumn":"wishlist",
        "unconditional" : [
            "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
            "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
            "DFFEDE1D-E423-2472-FF71-26EEC3F23700"
        ]
      }
    }    
  ]
}

Response:

{
    "success": true,
    "error": null,
    "results": {
        "add_relationPerson1": {
            "type": "ADD_RELATION",
            "result": 3
        }
    }
}

Request:

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "operations": [
    {
      "operationType": "FIND",
      "table": "Gift",
      "opResultId": "findGiftsOperation",
      "payload": {
        "whereClause":"name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')"
      }
    },
    {
      "operationType": "ADD_RELATION",
      "table": "Person",
      "opResultId": "addRelationOperation",
      "payload": {
        "parentObject" : "E7AD83E0-1B4E-D250-FF46-61BFAB18D700",
        "relationColumn":"wishlist",
        "unconditional" : {
            "___ref":true,
            "opResultId": "findGiftsOperation"
        }
      }
    }    
  ]
}

Response:

{
    "success": true,
    "error": null,
    "results": {
        "findGiftsOperation": {
            "type": "FIND",
            "result": [
                {
                    "price": 899.0,
                    "created": 1585540692000,
                    "name": "Apple iPhone",
                    "updated": 1585540695000,
                    "objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
                    "ownerId": null,
                    "___class": "Gift"
                },
                {
                    "price": 23.0,
                    "created": 1585540722000,
                    "name": "Selfie Stick",
                    "updated": 1585540766000,
                    "objectId": "E39EE103-9873-C0DB-FFD7-2E1CDD7D6600",
                    "ownerId": null,
                    "___class": "Gift"
                },
                {
                    "price": 399.0,
                    "created": 1585540683000,
                    "name": "Apple iPad",
                    "updated": 1585540686000,
                    "objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
                    "ownerId": null,
                    "___class": "Gift"
                }
            ]
        },
        "addRelationOperation": {
            "type": "ADD_RELATION",
            "result": 3
        }
    }
}

Request:

URL: 

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header: 
Content-Type:application/json
Request body: 
{
  "operations": [
      {
      "operationType": "FIND",
      "table": "Person",
      "opResultId": "findPersonOperation",
      "payload": {
        "whereClause":"name = 'John Doe'"
      }
    },
    {
      "operationType": "FIND",
      "table": "Gift",
      "opResultId": "findGiftsOperation",
      "payload": {
        "whereClause":"name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')"
      }
    },
    {
      "operationType": "ADD_RELATION",
      "table": "Person",
      "opResultId": "addRelationOperation",
      "payload": {
        "parentObject" : {
            "___ref":true,
            "opResultId": "findPersonOperation",
            "resultIndex" : 0,
            "propName" : "objectId"
        },
        "relationColumn":"wishlist",
        "unconditional" : {
            "___ref":true,
            "opResultId": "findGiftsOperation"
        }
      }
    }    
  ]
}

Response:

{
    "success": true,
    "error": null,
    "results": {
        "findPersonOperation": {
            "type": "FIND",
            "result": [
                {
                    "name": "John Doe",
                    "created": 1585533585000,
                    "updated": 1585584982000,
                    "objectId": "E7AD83E0-1B4E-D250-FF46-61BFAB18D700",
                    "ownerId": null,
                    "age": 36.0,
                    "___class": "Person"
                }
            ]
        },
        "findGiftsOperation": {
            "type": "FIND",
            "result": [
                {
                    "price": 899.0,
                    "created": 1585540692000,
                    "name": "Apple iPhone",
                    "updated": 1585540695000,
                    "objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
                    "ownerId": null,
                    "___class": "Gift"
                },
                {
                    "price": 23.0,
                    "created": 1585540722000,
                    "name": "Selfie Stick",
                    "updated": 1585540766000,
                    "objectId": "E39EE103-9873-C0DB-FFD7-2E1CDD7D6600",
                    "ownerId": null,
                    "___class": "Gift"
                },
                {
                    "price": 399.0,
                    "created": 1585540683000,
                    "name": "Apple iPad",
                    "updated": 1585540686000,
                    "objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
                    "ownerId": null,
                    "___class": "Gift"
                }
            ]
        },
        "addRelationOperation": {
            "type": "ADD_RELATION",
            "result": 3
        }
    }
}