Skip to content

Deleting from a relation

This operation deletes child objects from a parent in a relationship. The operation does not delete the actual objects, neither it deletes the relationship column. The operation simply disconnects the child objects from the parent.

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": "DELETE_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 "DELETE_RELATION" , this designates the operation as "disconnecting child objects from the parent object for a relation". The objects to remove as children from 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 disconnected from 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 disconnected from the parent 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": "DELETE_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 "DELETE_RELATION" , this designates the operation as "disconnecting child objects from the parent object for a relation". The objects to remove as children from 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 disconnected from 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 disconnected from 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": "DELETE_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 "DELETE_RELATION" , this designates the operation as "disconnecting child objects from the parent object for a relation". The objects to remove as children from 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 disconnected from 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 deleted from 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": "DELETE_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": {
        "delete_relationPerson1": {
            "type": "DELETE_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": "DELETE_RELATION",
      "table": "Person",
      "opResultId": "deleteRelationOperation",
      "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"
                }
            ]
        },
        "deleteRelationOperation": {
            "type": "DELETE_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": "DELETE_RELATION",
      "table": "Person",
      "opResultId": "deleteRelationOperation",
      "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"
                }
            ]
        },
        "deleteRelationOperation": {
            "type": "DELETE_RELATION",
            "result": 3
        }
    }
}