Declarative Objectivity (DO) Language : Data Clauses : ADD Clause
ADD Clause
An ADD clause adds one or more elements to a variable-size collection.
Syntax 
addClause : ADD addElement | addElements TO targetCollection;
addElement : expression | ('{' expression : expression '}');
addElements : '{' addElement (',' addElement)* '}' ;
targetCollection : reachableValue;
Used In 
UPDATE Statement
Quick Look 
Add an initial service record (represented as a string) to every vehicle with an empty list of service records, and return their licenses:
UPDATE Vehicles WHERE IS_EMPTY(servRecs) ADD 'Not yet serviced' TO servRecs RETURN license;
Add two dates to a rental company’s list of high-volume dates, and return just the updated list:
UPDATE RentalCompany ADD {2017-01-31, 2017-07-05} TO highVolumeDates RETURN highVolumeDates;
Add a rental contract with the specified object identifier to the rentals associated with a particular customer. The added element is a reference to an existing RentalContract object:
UPDATE Customer WHERE lastName == 'Mertz' ADD 3-3-1-8 TO rentals;
Add a reservation to the rental events associated with the first rental contract in a particular customer’s collection of rentals. The added element is a reference to an existing Reservation object, where Reservation is a subclass of RentalEvent:
UPDATE Customer WHERE lastName == 'Mertz' ADD 3-3-1-11 TO rentals[0].events;
Add a customer to the rental company. Because the collection of customers is a name map, the added element is a string key mapped to a reference:
UPDATE RentalCompany ADD {'fsmith123':3-3-1-13} TO customers;
Create a new RentalContract and add it to a Customer’s collection of rentals:
LET rc = CREATE RentalContract{trackingNumber == 312};
UPDATE Customer WHERE lastName == 'Mertz' ADD $rc TO rentals;
Find an existing RentalContract and add it to a Customer’s collection of rentals:
LET rc = FROM RentalContract WHERE trackingNumber == 728 RETURN *;
UPDATE Customer WHERE lastName == 'Mertz' ADD $rc[0].__identifier__ TO rentals;
  
Discussion 
An ADD clause occurs in an UPDATE Statement, and adds one or more elements to the target collection returned by the targetCollection expression. An error occurs if targetCollection does not return a single collection.
The target collection must be a variable-size collection. An error occurs if targetCollection returns a fixed-size collection. (When a collection is fixed-size, you set its elements individually; see Setting List Elements.)
The target collection may be the value of a direct or indirect attribute of the current context object.
You specify the value of an added element using an expression. You can add multiple elements by specifying multiple comma-separated expressions enclosed in curly braces. Each such expression could be a simple literal expression, or it could be a more complex operator expression, where the operands may be literals, attribute values of the current context object, and so on.
The ADD operation updates the target collection by adding the appropriate number of empty elements, and then setting each new element’s value to be equal to the value returned by a specified expression.
The value returned by the specified expression(s) must be of a type that is expected by the target collection for its elements. For example, if the elements of the specified target collection are date values, the specified expression(s) must return a date value.
If the target collection is a list, new elements are added to the end of the list. If the target collection is a set or a map, the ordering of each new element relative to existing elements is controlled by the collection. New elements are sorted into a tree-based collection, and hashed into a hash-based collection.
Adding to a Collection of References
When the elements of the target collection are references to persistent objects, the added element can be a reference to a newly created object:
You can use a nested CREATE Statement to create (and obtain a reference to) a new object of the referenced class or a subclass of that class:
UPDATE Location WHERE airportCode == 'SJC' ADD CREATE Stall{number: 1} TO stalls;
You can use LET to assign the result of a CREATE Statement to a parameter, and then specify the parameter as the value to be added:
LET s = CREATE Stall{number: 1};
UPDATE Location WHERE airportCode == 'SJC' ADD $s TO stalls;
Note:If more than one Location is qualified by the WHERE clause, the above examples will create a separate Stall object to add to each Location’s stalls collection. Each new Stall object would have the same specified value for its number attribute (in this case, 1), but would have a unique object identifier.
Alternatively, the added element can be a reference to an existing object:
You can use an object identifier (OID literal) to specify a reference to an existing object. The object must be of the referenced class or a subclass of that class:
UPDATE Customer WHERE lastName == 'Mertz' ADD 3-3-1-8 TO rentals RETURN rentals;
You can use a LET statement to query for the object of interest, and assign the result to a parameter. You then extract the reference from the parameter (see Obtaining a Reference to an Existing Object From a Parameter), and add the reference to the collection:
LET rc = FROM RentalContract WHERE trackingNumber == 728 RETURN trackingNumber;
UPDATE Customer WHERE lastName == 'Mertz' ADD $rc[0].__identifier__ TO rentals RETURN rentals;
Adding to a Collection of Bidirectional References
When the elements of the target collection are bidirectional references to persistent objects, the ADD operation automatically updates the element being added, in addition to updating the collection.
Example. Assume the schema defines a bidirectional relationship between the Customer class and the RentalContract class through a pair of inverse reference attributes (namely, the Customer’s rentals attribute and the RentalContract’s customer attribute). This enables a customer to have multiple rental contracts, where each rental contract belongs to exactly one customer. Now consider what happens when a customer acquires a new rental contract:
UPDATE Customer WHERE lastName == 'Mertz' ADD 3-3-1-8 TO rentals RETURN rentals;
This statement performs the following actions:
Explicitly adds the specified RentalContract to the Customer’s rentals collection.
Implicitly sets the inverse customer attribute in the RentalContract to reference the updated Customer.
Adding to a Collection of Embedded Objects
When the elements of the target collection are embedded objects:
You can use an object structure to specify the attribute values of the newly added embedded object.
Example. Assume Address is an embeddable class, and addressBook is a list attribute:
UPDATE Person WHERE name == 'Bob' ADD Address{street:'321 Easy St.', city:'San Jose', zip:'95128'} TO addressBook;
The object structure must include the name of the appropriate embeddable class or a subclass of that class.
The specified object structure specifies the entire embedded object. Attributes that are included in the object structure are set to the specified values; any attributes not specified by the object structure are set to default values.
Adding to a Map
When the target collection is a map:
You specify each new element as a key:value pair, where key and value are expressions whose return types are compatible with the key and value types defined for the map.
The element or elements being added must be enclosed in curly braces.
Example. Assume the rental company’s collection of customers is a name map. The following statement adds a single new element, which is a string key mapped to an object reference:
UPDATE RentalCompany ADD {'fsmith123':3-3-1-13} TO customers;
Example. The following statement adds multiple new elements to the customers list:
UPDATE RentalCompany ADD MAP{'fsmith123':3-3-1-13, 'msuarez':3-3-12-52} TO customers;