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"));