Function

a!update( data, index, value )

Inserts new values or replaces existing values at the specified index or field name and returns the resulting updated data.

See also:

• insert(): Use this function if you want to insert new values into a list without replacing existing values.
• append(): Use this function if you want to append values to the end of a list.
• Inserting a Value into an Index of an Array: If you plan to use this function on a node output and simply want to insert one or more values into an array, check out the Is Stored at Index operator discussed in this help topic which provides this specific functionality.

Parameters

Keyword	Type	Description
data	Any Type	A list, map, dictionary, CDT, or record containing data to be updated.
index	Any Type	The index or field at which to update the data.
value	Any Type	The new value to add or replace an existing value.

Returns

Any Type

Usage considerations

Using the data parameter

The data parameter must be a collection such as a list, map, dictionary, CDT, or record. Scalars like text, integers, and dates cannot be updated.

If the data parameter is passed a typed list, such as List of Text or List of Integer, the value parameter must be of the same type. Otherwise, a!update() will attempt to cast the value parameter to the appropriate type for the list. If the cast is not possible, an error will occur. For example, when updating a List of Text with an Integer, the Integer will be cast to Text in the updated list.

Limitations and alternatives

Do not use maps, dictionaries, CDTs, or records which contain fields that differ only in casing.

Examples

Updating an item in a list

a!update(data: {1, 2, 3}, index: 1, value: 5) returns {5, 2, 3}

a!update(data: {"ab", "cd"}, index: 2, value: 3) returns {"ab", "3"}. The Integer 3 was cast to a Text "3" since the data parameter was a List of Text.

a!update(data: {"ab", "cd"}, index: null, value: "ef") returns {"ab", "cd"}. A null index will result in no update to the data.

Appending an item to a list

If the index is greater than the length of the list, null values are added in between the end of the original list and the new value.

a!update(data: {1, 2, 3}, index: 4, value: 4) returns {1, 2, 3, 4}

a!update(data: {1, 2, 3}, index: 6, value: 11) returns {1, 2, 3, null, null, 11}.

Updating or appending multiple items to a list

a!update(data: {1, 2, 3}, index: {1, 4}, value: 11) returns {11, 2, 3, 11}

a!update(data: {1, 2, 3}, index: {1, 4}, value: {11, 14}) returns {11, 2, 3, 14}

a!update(data: {}, index: {2, 4}, value: 11) returns {null, 11, null, 11}. Since the data parameter was an empty list, updating non-consecutive indices results in null values being added in the remaining indices.

a!update(data: {}, index: {2, 4}, value: {11, 13}) returns {null, 11, null, 13}

Updating a map, record, CDT, or dictionary with a field name

In order to test the CDT or record examples, you will need to create a CDT or record type with the same field names. For record examples, use record field references instead of strings shown in the examples below.

a!update(data: a!map(a: 1, b: 2), index: "a", value: 5) returns a!map(a: 5, b: 2)

a!update(data: {a: 1, b: 2}, index: "a", value: 5) returns {a: 5, b: 2}

In this example, there is a CDT called "Customer" with 3 fields on it: id, name, and age.

a!update(data: type!Customer(id: 3, name: "John", age: 30), index: "age", value: 31) returns type!Customer(id: 3, name: "John", age: 31)

In this example, there is a record type called "Customer" with 3 fields on it: id, name, and age.

a!update(data: recordType!Customer(id: 4, name: "Jane", age: 42), index: recordType!Customer.fields.age, value: 43) returns recordType!Customer(id: 4, name: "Jane", age: 43)

Updating a nested CDT or related record with a field name

In order to test the CDT or record examples, you will need to create a CDT or record type with the same field names.

In this example, the top level CDT called "mainCDT" has a nested CDT inside of it called "nestedCDT" which has one field called "field1".

a!update(data: type!mainCDT(nestedCDT: type!nestedCDT(field1: "abc")), index: "nestedCDT", value: a!update(data: type!nestedCDT(field1: "abc"), index: "field1", value: "New Value")) returns type!CDT(nestedCDT: type!nestedCDT(field1: "New Value"))

In these examples, the record type "Customer" has a 1:1 relationship with the record type "Address"

a!update(data: recordType!Customer(Address: recordType!Address(zip: 12345)), index: recordType!Customer.relationships.Address.fields.zip, value: 23456) returns recordType!Customer(Address: recordType!Address(zip: 23456))

a!update(data: recordType!Customer(Address: null), index: recordType!Customer.relationships.Address, value: recordType!Address(zip: 12345)) returns recordType!Customer(Address: recordType!Address(zip: 12345))

Updating multiple values across a list of maps, records, CDTs, or dictionaries

a!update(data: {a!map(x:10, y:20), a!map(x:1, y:2)}, index: "x", value: {-10, -1}) returns {a!map(x: -10, y: 20), a!map(x: -1, y:2)}

Inserting a key into a map or dictionary

a!update(data: a!map(a: 1, b: 2), index: "c", value: 3) returns a!map(a: 1, b: 2, c: 3)

a!update(data: a!map(), index: "a", value: 1) returns a!map(a: 1)