Skip to content

Setting a relation

This operation creates a relationship between a parent and child objects. If the parent object already has other related children, the relationship is reset - the child objects identified in this operation become the sole children of the parent. If you're looking for an operation which adds child objects to an existing set of children, see the Adding to a relation chapter of this guide.

Important

It is important that the relation column in the parent table is created before a transaction with the operation runs.

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://api.backendless.com/APP-ID/REST-API-KEY/transaction/unit-of-work
Request header:
Content-Type:application/json
Request body:
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "SET_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 "SET_RELATION", this designates the operation as "setting child objects to a parent object for a relation". The objects to set 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.
"payload" > "columnName" The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are set 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 set  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://api.backendless.com/APP-ID/REST-API-KEY/transaction/unit-of-work
Request header:
Content-Type:application/json
Request body:
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "SET_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 "SET_RELATION", this designates the operation as "setting child objects to a parent object for a relation". The objects to set 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 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.
"payload" > "columnName" The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are set 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 set as children to the parent object for the "columnName" relation.

URL:

POST https://api.backendless.com/APP-ID/REST-API-KEY/transaction/unit-of-work
Request header:
Content-Type:application/json
Request body:
{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "SET_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 "SET_RELATION", this designates the operation as "setting child objects to a parent object for a relation". The objects to set 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.
"payload" > "columnName" The value is mandatory. Must contain the name of the column which identifies the relationship for which the child objects are set 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 set in the relation. The returned value can be used in other operations of the same transaction.

Examples

All examples below perform the same operation of linking objects from the Gift table to an object from the Person table through a column called wishlist. This is what the parent table looks like:

person-table-parent.zoom70

You can see the wishlist column, which is a one-to-many relation with the Gift table shown below:

gifts-table-children.zoom70

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

Request:

URL:

POST https://api.backendless.com/APP-ID/REST-API-KEY/transaction/unit-of-work
Request header:
Content-Type:application/json
Request body:
{
  "operations": [
     {
      "operationType": "SET_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": {
        "set_relationPerson1": {
            "type": "SET_RELATION",
            "result": 3
        }
    }
}

Request:

URL:

POST https://api.backendless.com/APP-ID/REST-API-KEY/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": "SET_RELATION",
      "table": "Person",
      "opResultId": "setRelationOperation",
      "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"
                }
            ]
        },
        "setRelationOperation": {
            "type": "SET_RELATION",
            "result": 3
        }
    }
}

Request:

URL:

POST https://api.backendless.com/APP-ID/REST-API-KEY/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": "SET_RELATION",
      "table": "Person",
      "opResultId": "setRelationOperation",
      "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"
                }
            ]
        },
        "setRelationOperation": {
            "type": "SET_RELATION",
            "result": 3
        }
    }
}

The screenshot below is what the Person object will look like in Backendless Console. Notice the wishlist relation column now indicates there are related child objects:

parent-table-after-setrelation.zoom70