a!update() Function

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

Syntax

a!update( data, index, value )

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

Notes

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.

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

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.

a!update(data: {"ab", "cd"}, index: 2, value: 3)
returns
{"ab", "3"}

Examples

Updating an item in a list

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

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

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

Appending an item to a list

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

  2. a!update(data: {1, 2, 3}, index: 6, value: 11)
    returns
    {1, 2, 3, null, null, 11}
    Note: 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.

Updating or appending multiple items to a list

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

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

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

  4. 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.

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

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

  3. 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)

  4. 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)

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

  1. 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"))

  2. In this example, 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))

  3. In this example, the record type "Customer" has a 1:1 relationship with the record type "Address"
    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

  1. 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

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

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

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.

Open in Github

On This Page

FEEDBACK