Update Expression

On This Page

Overview

An update expression is an expression that is used to update the attributes of an item. This includes adding attributes and initializing their values, changing the value of existing attributes, or removing (deleting) item attributes. For example, the NoSQL Web API UpdateItem operation receives an update-expression request parameter (UpdateExpression), and optionally also an alternate update-expression parameter for an if-then-else update (AlternateUpdateExpression), that define which item attributes to update and how to update them.

Arrays Support
In the current release, the support for array attributes and the use of array operators and functions in expressions is restricted to the web APIs.

Syntax

KEYWORD ACTION[; KEYWORD ACTION; ...]

An update expression is composed of one or more update-action expressions, each made up of an action keyword (KEYWORD) followed by a matching action expression (ACTION). (In some cases, the keyword can be omitted, as outlined in the documentation.) The action expressions are separated by semicolons (;). Spaces around the semicolons are ignored. The last update-action expression can optionally be terminated with a semicolon as well.

Note
Expression keywords are reserved names in the platform. For more information, see Reserved Names.

The following update expression types are supported:

  • SET expression — sets the value of an item attribute (including creation of the attribute if it doesn't already exist) or of an element in an array attribute.
  • REMOVE expression — removes (deletes) an item attribute.

SET Expression

SET ELEMENT = VALUE

A SET expression updates the value of an attribute or an element in an array attribute. When updating an attribute that isn't already found in the updated item, the platform creates the attribute and initializes it to the specified value.

A SET expression can optionally begin with the SET keyword, which is the default keyword for assignment expressions. The expression contains an assignment expression that consists of an assignment operator (=) whose operands are the updated element (ELEMENT) — an attribute (ATTRIBUTE), a slice of an array attribute (ATTRIBUTE[istart..iend]), or an element of an array attribute (ATTRIBUTE[i]) — and the value to assign (VALUE). VALUE can also be an expression that evaluates to the value to assign — for example, "SET myattr = 4 + 5;".

Note
In the current release, you cannot directly assign Base64 encoded strings to blob attributes in expressions. However, you can define and update blob array attributes in expressions — see Array-Attribute Expression Variables.

REMOVE Expression

REMOVE ATTRIBUTE

A REMOVE expression removes an attribute from an item (i.e., deletes the attribute).

The expression begins with the REMOVE keyword followed by the name of the attribute to remove (ATTRIBUTE).

Examples

  1. Increment the current value of an existing miles attribute by 1000:

    "SET miles = miles + 1000"

  2. Remove an item's miles attribute:

    "REMOVE miles"

  3. Update the values of two grocery-department income attributes (produce and dairy), and set the value of a sum attribute to the sum of the updated department-income attribute values:

    "produce=20000; dairy=15000; sum = produce + dairy"

  4. Set the value of a rainbow string attribute:

    "SET rainbow='red, orange, yellow, green, blue, indigo, violet'"

  5. Initialize multiple attributes of different types in a person item:

    "SET name='Alexander Bell'; country='Scotland'; isMarried=true; numChildren=4"

  6. Add and initialize a ctr counter attribute to 1 if it doesn't already exist; if the attribute exists, increment its value by 1 (see if_not_exists):

    "SET ctr = if_not_exists(ctr,0) + 1;"

  7. Add new attributes to an item and initialize their values; if the attributes already exist, they will be reassigned their current values (see if_not_exists):

    "SET color = if_not_exists(color, 'red'); SET updated = if_not_exists(updated, true)"

  8. Switch the values of two attributes (a and b) using a temporary temp attribute, and then delete the temporary attribute. Attributes a and b must already be defined for the item:

    "temp=b; b=a; a=temp; REMOVE temp"

  9. Create a new counters integer array attribute with five elements, all initialized by default to zero:

    "SET counters = init_array(5, 'int')"

  10. Create a new smallArray array attribute from the first five elements of an existing myArray array attribute:

    "smallArray = myArray[0..4]"

  11. Update the values of the first four elements of an arr array attribute. The fourth attribute (at index 3) is assigned the result of an arithmetic expression that uses the updated values of the first three array elements:

    "arr[2]=-1; arr[0]=6; arr[1]=7; arr[3]=arr[0]+arr[2]*arr[1]"

  12. Define an arrSmallFibonacci integer array attribute of five elements that implements a small Fibonacci series in which each element (beginning with the third element) is the sum of the previous two elements; (the value of the first element, at index 0, is 0 — init_array default):

    "arrSmallFibonacci = init_array(5, 'int'); arrSmallFibonacci[1]=1; arrSmallFibonacci[2] = arrSmallFibonacci[0] + arrSmallFibonacci[1]; arrSmallFibonacci[3] = arrSmallFibonacci[1] + arrSmallFibonacci[2]; arrSmallFibonacci[4] = arrSmallFibonacci[2] + arrSmallFibonacci[3];"

  13. Define an arrFibonacci integer array attribute of 100 elements and an i loop-iterator number attribute, and use the attributes to implement a Fibonacci series in which each element (beginning with the third element) is the sum of the previous two elements.

    1. Define the attributes and initialize the values of i and of the first three elements of the arrFibonacci array; (the initialization to 0 of the first element, at index 0, could have been omitted because it's the default value):

      "i=2; arrFibonacci = init_array(100,'int'); arrFibonacci[0]=0; arrFibonacci[1]=1; arrFibonacci[2] = arrFibonacci[0] + arrFibonacci[1]"

    2. Repeatedly update the item using the following update expression to sequentially update the series elements in the array (starting from the fourth element at index 3):

      "i=i+1; arrFibonacci[i] = arrFibonacci[i-1] + arrFibonacci[i-2];"

      You can use a condition expression to set the maximum number of array elements to update. For example, the following expression limits the update to 55 elements:

      "i<55"

    3. At the end, you can optionally use a REMOVE update expression to delete the i attribute:

      "REMOVE i"

See Also