Relations API (Set/Add) Overview¶
Important
This and other relation API sections refer to objects in a relation as parent and child(ren). The parent object is the one that contains a reference to a related object. A child object is one that is being referenced by the parent.
There are two operations supporting creating a relation between objects:
| Operation |
Description |
|---|---|
Setting a relation |
Sets specified child objects as the related objects for the parent. If the parent had other child objects prior to the operation, the relation between them and the parent is removed. This is a replacement operation. |
Adding a relation |
This operation adds specified child objects to the collection of existing child objects. This is a concatenation operation. For one-to-one relations, if the parent object has a child for the specified column at the time when the operation is called, an error is returned back to the client |
Other implementation details:
| Details |
|---|
| Both parent and child objects must exist in the Backendless storage. |
| If a column identifies a 1:1 relation which already exists between the parent and some other object, the "set" operation must replace the child object with the one identified in the operation. The "add" operation must return an error. |
| Add/set methods must return the number of objects added/set, that is, for example, if a whereClause is used and identifies an object (among others) which is already in the relation, that object must not be "accounted for" in the returned number of object. |
| If add/set receives a non-existing object, it must be ignored and the returned count of objects set/added must not reflect the ignored object. |
| Both operations create the relation column if it does not exist at the time of the method call. |
There are two ways to add/set a relation:
- Explicit relation list an API request identifies specific objects to be added/set as children of the parent object. Available APIs:
Set Relation
Add Relation - Implicit relation list - an API request uses a query (the where clause) to identify objects which should be added/set as children of the parent object. Available APIs:
Set Relation
Add Relation