Expressions Overview

On This Page

The platform APIs support the use of expressions to define execution logic and enhance the support for working with NoSQL items (objects) and their attributes.

Condition expressions define a logical condition for performing a specific operation.
Update expressions can be used to add and initialize item attributes, update the values of existing attributes or elements in an array attribute, or remove (delete) attributes.

This reference outlines the supported expressions and their syntax.

Expression

The EXPRESSION notation represents a basic expression syntax, which can also be included in other expressions. An expression is typically defined as a string that can include a combination of any of the following components (depending on the context).

Note
The document uses XXX notations, such as FUNCTION and ATTRIBUTE, as placeholder identifiers for the related components.
Note
  • The names of the expression functions and operands are case insensitive. For example, color in (red, blue) and color IN (red, blue) both work (see the in operator).
  • String values within the expression are enclosed within single quotes (' ').
  • Expression keywords, including the names of expression operators, are reserved names in the platform. For more information, see Reserved Names.
  • See the Software Specifications and Restrictions for known expression restrictions.

Literals

LITERAL

LITERAL represents a constant literal value. For example: 'blue'; 5; true.

Attribute Variables

ATTRIBUTE

ATTRIBUTE in expressions represents an attribute variable, which is the name of an item attribute — for example, first-name or color.

Attribute variables can refer to any supported attribute type, including system attributes such as __mtime_secs or __uid.

Note
"attribute value" in the expressions documentation refers to the attribute data value. In the NoSQL Web API Reference, this refers to the value of an Attribute Value object.

If an attribute name is a reserved word, such as a function name, enclose the word within acute-accent characters (`) — `<reserved word>`. For example, for an attribute named exists, use "`exists` == true".

Note
Expressions enable you to use attributes as variables in arithmetic or logical calculations and evaluations. For example, you can define an i attribute to be used as a loop iterator, and increment or decrement its value sequentially.

Array-Attribute Expression Variables

The platform enables you to define array attributes as special blob attributes that identify Base64 encoded integer or double arrays.

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

Array attributes are defined in SET update expressions — for example, in the UpdateExpression request parameter of the NoSQL Web API UpdateItem operation. You can either use the init_array expression function to define and initialize a new array attribute (for example, "SET arr=init_array(100,'double')"), or assign an existing array attribute or a slice of such an attribute to a new array attribute (for example, "SET newArr=oldArr" or "SET newArr=oldArr[0..99]").

The elements of an array attribute can be referenced in expressions using the array operator ([ ]).

Boolean Conversions

In most cases, Boolean values can also be used as numeric operands: the platform implicitly converts true to 1 and false to 0. For example, the following update expression is valid, implicitly converting the results of the embedded Boolean expressions to 1 or 0: res=(1 in (1,2,3,4,5))*10 + (starts('abc','xx'))*100 + (ends('abc','bc'))*1000 + (contains('abxxc','xx'))*100000;. However, this doesn't apply to attribute comparisons because the platform verifies that the compared value matches the current attribute data type. For example, if the value of attribute a is 5 (integer) and the value of attribute b is false (Boolean), the expressions a==true and b==0 will both fail because of a type mismatch. But an expression such as "c = (a==5)*4 + b;" will succeed — implicitly converting the result of the a==5 comparison from true to 1 and the value of b (false) to 0 and setting the value of attribute c to 4 (1*4+0).

See Also