Skip to content

Set/Add Relation using a condition

In this API request, child objects are referenced implicitly - through a whereClause defining the condition for object selection.


Set relation - POST

Add relation - PUT

Endpoint URL

The is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.<table-name>/<parentObjectId>/<relationName>?whereClause=<whereClause> 


Argument                Description
<table-name> name of the table where which contains the parent object as identified by <parentObjectId>.
<parentObjectId> id of the object for which the relation will be created/set.
<relationName> name of the column which identifies the relation within the parent table (identified as <table-name>). The column name may optionally include table name separated by the colon character as well as cardinality which determines the type of relationship (one to one or one to many) (see the note below):


If the column does not exist in the parent table at the time when the API is called, the value of the "relationColumnName" argument must include the name of the child table separated by colon and the cardinality notation. The cardinality is expressed as ":1" for one-to-one relations and ":n" for one-to-many relations. For example, the value of "myOrder:Order:1" will create a one-to-one relation column "myOrder" in the parent table. The column will point to the Order child table. Likewise, the value of "myOrder:Order:n" will create a one-to-many relation column "myOrder" pointing to the Order table.

Argument                Description
<whereClause> a where clause condition identifying objects in the child table which will be set as the related objects for the parent object.

Request Headers

user-token: value-of-the-user-token-header-from-login


Argument                Description
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the operation will be executed with the security policy associated with the currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body


Return Value

Error or number of objects the operation sets for the relation.


The following request creates a relation between a Person object and all objects in the Users table which match the provided query. The query is specified in the whereClause parameter in the URL. The value of the whereClause parameter is URL-encoded. The decoded version of the query is: name='Joe' or name = 'Frank'. As a result of the operation, all User objects where the name property is either Joe or Frank will be set in the relation.

The relation column is created if it does not exist. This is done because the column contains the child table qualifier, defined as ":Users:n" right after the column name.


Make sure to replace xxxx in the domain name in the sample request below to the one assigned to your application.

curl \