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.

// Add the objects represented by the "children" 
// argument to the children of the parent object.
// The "children" argument can be either:
//   - a whereClause
//   - OpResult 
//   - list of the objectId/Map/Custom class object values.
//
// The "parent" argument can be:
//   - a Map
//   - objectId
//   - custom class instance
//   - OpResult
//   - OpResultValueReference.
unitOfWorkInstance.addToRelation(dynamic parent, 
                               String columnName, 
                               dynamic children, 
                               [String parentTable]);

Return Value

The operation returns an OpResult object which represents the result of this operation - number of child objects added to the relation.

Examples

The examples are organized by two levels: first is how the parent object is represented in the client program, then by the type of the child collection.

Parent object is represented as

** The child objects are represented as**

final unitOfWork = UnitOfWork();

// This is an array for child objects.
// They are referenced using objectId values.
// The example hard-codes the array, but in
// your code you'd get the objectId values
// from your data model or using a query
final giftIds = [
   "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
   "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
   "DFFEDE1D-E423-2472-FF71-26EEC3F23700"];

// this is the objectId of the parent object.
final personObjectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObjectId,
   relationColumnName,
   giftIds,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
final unitOfWork = UnitOfWork();

final iPad = {
 "objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
};

final iPhone = {
 "objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
};

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the objectId of the parent object.
final personObjectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObjectId,
   relationColumnName,
   gifts,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

final unitOfWork = UnitOfWork();

final iPad = Gift()
 ..objectId = "EE3BF4B5-DB88-1425-FF89-CC11B7707500";

final iPhone = Gift()
 ..objectId = "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200";

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the objectId of the parent object.
final personObjectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObjectId,
   relationColumnName,
   gifts,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
The Gift class is shown below:
@reflector
class Gift {
   String objectId;
   String name;
   double price;
}

final unitOfWork = UnitOfWork();

// compose a query to fetch the gift objects
final queryBuilder = DataQueryBuilder();
queryBuilder.whereClause = "name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')";

// add the find operation to the transaction
// notice the result of the operation is saved in a variable -
// it will be used further in the addToRelation operation
final gifts = unitOfWork.find("Gift", queryBuilder);

// this is the objectId of the parent object.
final personObjectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObjectId,
   relationColumnName,
   gifts,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

** The child objects are represented as**

final unitOfWork = UnitOfWork();

// This is an array for child objects.
// They are referenced using objectId values.
// The example hard-codes the array, but in
// your code you'd get the objectId values
// from your data model or using a query
final giftIds =[
   "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
   "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
   "DFFEDE1D-E423-2472-FF71-26EEC3F23700"];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = {
 "objectId": "E7AD83E0-1B4E-D250-FF46-61BFAB18D700"
};

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   giftIds,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
final unitOfWork = UnitOfWork();

final iPad = {
"objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500"
};

final iPhone = {
"objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200"
};

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = {
"objectId": "E7AD83E0-1B4E-D250-FF46-61BFAB18D700"
};

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   gifts,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

final unitOfWork = UnitOfWork();

final iPad = Gift()
 ..objectId = "EE3BF4B5-DB88-1425-FF89-CC11B7707500";

final iPhone = Gift()
 ..objectId = "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200";

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = {
 "objectId": "E7AD83E0-1B4E-D250-FF46-61BFAB18D700"
};

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation( 
   personObject,
   relationColumnName,
   gifts,
   parentTableName);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
The Gift class is shown below:
@reflector
class Gift {
   String objectId;
   String name;
   double price;
}

final unitOfWork = UnitOfWork();

// compose a query to fetch the gift objects
final queryBuilder = DataQueryBuilder();
queryBuilder.whereClause = "name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')";

// add the find operation to the transaction
// notice the result of the operation is saved in a variable -
// it will be used further in the addToRelation operation
final gifts = unitOfWork.find("Gift", queryBuilder);

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = {
 "objectId": "E7AD83E0-1B4E-D250-FF46-61BFAB18D700"
};

// the name of the table where the parent object is stored
final parentTableName = "Person";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   gifts,
   parentTableName
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

** The child objects are represented as**

final unitOfWork = UnitOfWork();

// This is an array for child objects.
// They are referenced using objectId values.
// The example hard-codes the array, but in
// your code you'd get the objectId values
// from your data model or using a query
final giftIds = [
   "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
   "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
   "DFFEDE1D-E423-2472-FF71-26EEC3F23700"];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = Person()
 ..objectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   giftIds
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
final unitOfWork = UnitOfWork();

final iPad = {
 "objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500"
};

final iPhone = {
"objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200"
};

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = Person()
 ..objectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   gifts
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

final unitOfWork = UnitOfWork();

final iPad = Gift()
 ..objectId = "EE3BF4B5-DB88-1425-FF89-CC11B7707500";

final iPhone = Gift()
 ..objectId = "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200";

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = Person()
 ..objectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   gifts
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
The Gift class is shown below:
@reflector
class Gift {
   String objectId;
   String name;
   double price;
}

final unitOfWork = UnitOfWork();

// compose a query to fetch the gift objects
final queryBuilder = DataQueryBuilder();
queryBuilder.whereClause = "name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')";
// add the find operation to the transaction
// notice the result of the operation is saved in a variable -
// it will be used further in the addToRelation operation
final gifts = unitOfWork.find("Gift", queryBuilder);

// this is the parent object. The only property that
// matters for the sake of establishing a relation
// is objectId. In your program you would be
// retrieving the object from the server. The
// technique shown here is for code brevity.
final personObject = Person()
 ..objectId = "E7AD83E0-1B4E-D250-FF46-61BFAB18D700";

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   personObject,
   relationColumnName,
   gifts
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

** The child objects are represented as**

final unitOfWork = UnitOfWork();

// This is an array for child objects.
// They are referenced using objectId values.
// The example hard-codes the array, but in
// your code you'd get the objectId values
// from your data model or using a query
final giftIds = [
   "EE3BF4B5-DB88-1425-FF89-CC11B7707500",
   "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200",
   "DFFEDE1D-E423-2472-FF71-26EEC3F23700"];

// compose a query to retrieve the person
// from the database
final queryBuilder = DataQueryBuilder();

// this is the query which identifies the person of interest,
// this person object will be used as the parent in the relationship
queryBuilder.whereClause = "name = 'John Doe' and age = 36";

// add the object retriefinal operation to the transaction
final findResult = unitOfWork.find("Person", queryBuilder);

// since "findResult" references a collection of objects,
// get the first one from the collection. The reason we need to
// do this is because the addToRelation operation below
// expects only one parent object. We know the first object
// will be the parent, that's why the "resolveTo" index is 0.
final paarentObjectRef = findResult.resolveTo(resultIndex: 0);

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   paarentObjectRef,
   relationColumnName,
   giftIds
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
final unitOfWork = UnitOfWork();

final iPad = {
 "objectId": "EE3BF4B5-DB88-1425-FF89-CC11B7707500"
};

final iPhone = {
"objectId": "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200"
};

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// compose a query to retrieve the person
// from the database
final queryBuilder = DataQueryBuilder();
// this is the query which identifies the person of interest,
// this person object will be used as the parent in the relationship
queryBuilder.whereClause = "name = 'John Doe' and age = 36";

// add the object retriefinal operation to the transaction
final findResult = unitOfWork.find("Person", queryBuilder);

// since "findResult" references a collection of objects,
// get the first one from the collection. The reason we need to
// do this is because the addToRelation operation below
// expects only one parent object. We know the first object
// will be the parent, that's why the "resolveTo" index is 0.
final parentObjectRef = findResult.resolveTo(resultIndex: 0);

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   parentObjectRef,
   relationColumnName,
   gifts);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));

final unitOfWork = UnitOfWork();
final iPad = Gift()
 ..objectId = "EE3BF4B5-DB88-1425-FF89-CC11B7707500";

final iPhone = Gift()
 ..objectId = "0CF23E36-FCC0-4E04-FF3E-8B67E6E27200";

// This is a list of gift objects. These objects
// will be children in the relationship. As you
// can see the objects are constructed manually
// and their objectId's are set, however, in your
// application they would be loaded from the
// server. This is done here to keep the example
// more succinct.
final gifts = [iPad, iPhone];

// compose a query to retrieve the person
// from the database
final queryBuilder = DataQueryBuilder();
// this is the query which identifies the person of interest,
// this person object will be used as the parent in the relationship
queryBuilder.whereClause = "name = 'John Doe' and age = 36";

// add the object retriefinal operation to the transaction
final findResult = unitOfWork.find("Person", queryBuilder);

// since "findResult" references a collection of objects,
// get the first one from the collection. The reason we need to
// do this is because the addToRelation operation below
// expects only one parent object. We know the first object
// will be the parent, that's why the "resolveTo" index is 0.
final parentObjectRef = findResult.resolveTo(resultIndex: 0);

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   parentObjectRef,
   relationColumnName,
   gifts
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));
The Gift class is shown below:
@reflector
class Gift {
   String objectId;
   String name;
   double price;
}

final unitOfWork = UnitOfWork();

// compose a query to fetch the gift objects
final queryBuilder = DataQueryBuilder();
queryBuilder.whereClause = "name in ( 'Apple iPad', 'Apple iPhone', 'Selfie Stick')";

// add the find operation to the transaction
// notice the result of the operation is saved in a variable -
// it will be used further in the addToRelation operation
final gifts = unitOfWork.find("Gift", queryBuilder);
// compose a query to retrieve the person
// from the database
final parentQueryBuilder = DataQueryBuilder();
// this is the query which identifies the person of interest,
// this person object will be used as the parent in the relationship
parentQueryBuilder.whereClause = "name = 'John Doe' and age = 36";

// add the object retrieval operation to the transaction
final findResult = unitOfWork.find("Person", parentQueryBuilder);

// since "findResult" references a collection of objects,
// get the first one from the collection. The reason we need to
// do this is because the addToRelation operation below
// expects only one parent object. We know the first object
// will be the parent, that's why the "resolveTo" index is 0.
final parentObjectRef = findResult.resolveTo(resultIndex: 0);

// the name of the relation column
final relationColumnName = "wishlist";

// add the addToRelation call to the transaction
unitOfWork.addToRelation(
   parentObjectRef,
   relationColumnName,
   gifts
);

// run the transaction
unitOfWork.execute().then((result) => print("transaction complete - $result"));