UpdateItem

On This Page

Description

Updates the attributes of a table item. If the specified item or table don't exist, the operation creates them.

Request

Request Header

Syntax

POST /<container>/<resource> HTTP/1.1
Host: <web-APIs URL>
Content-Type: application/json
X-v3io-function: UpdateItem
<Authorization OR X-v3io-session-key>: <value>

url = "http://<web-APIs URL>/<container>/<resource>"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "UpdateItem",
            "<Authorization OR X-v3io-session-key>": "<value>"
          }

URL Resource Parameters

The path to the item to update. The path includes the table path and the item's name (primary key). You can optionally set the item name in the request's Key JSON parameter instead of in the URL; you can also optionally set the relative table path within the container, or part of the path, in the request's TableName JSON parameter.

Request Data

Syntax

{
    "TableName": "string",
    "Key": {
        "string": {
            "S": "string",
            "N": "string"
        }
    },
    "ConditionExpression":        "string",
    "UpdateExpression":           "string",
    "AlternateUpdateExpression":  "string"
}

payload = {
            "TableName": "string",
            "Key": {
                "string": {
                    "S": "string",
                    "N": "string"
                }
            },
            "ConditionExpression":        "string",
            "UpdateExpression":           "string",
            "AlternateUpdateExpression":  "string"
          }

Parameters

TableName

The table (collection) that contains the item — a relative table path within the configured data container or the end of such a path, depending on the resource configuration in the request URL. See Data-Service Web-API General Structure.
If the table doesn't exist, the operation will create it.

Type: String

Requirement: Required if not set in the request URL

Key

A primary-key attribute whose value is the item's primary-key value, which uniquely identifies the item within the table. The primary-key value is also the item's name and is stored by the platform in the __name system attribute. When defining the key for the UpdateItem request by setting the Key JSON request parameter (instead of setting the key in the URL), the platform also automatically defines a primary-key user attribute of the specified name, type, and value (the primary-key value). See also Item Name and Primary Key.

Note

To support range scans, use a compound <sharding key>.<sorting key> primary-key value. For more information, see Working with NoSQL Data.
See the primary-key guidelines in the Best Practices for Defining Primary Keys and Distributing Data Workloads guide.

Type: Attribute object

Requirement: Required if the item's name (primary key) is not set in the URL

UpdateExpression

An update expression that specifies the changes to make to the item's attributes. See Update Expression for syntax details and examples. You can optionally use the ConditionExpression request parameter to define a condition for executing the update expression. You can also use the AlternateUpdateExpression parameter to define an alternate update expression to execute if the condition expression evaluates to false. When the update expression is executed, it's evaluated against the table item to be updated, if it exists. If the item doesn't exist, the update creates it (as well as the parent table if it doesn't exist).

Note

To access the table with Spark DataFrames or Trino, the item must have a sharding-key user attribute, and in the case of a compound primary-key also a sorting-key user attribute; (for more efficient range scans, use a sorting-key attribute of type string). To access the table with V3IO Frames, the item must have a primary-key user attribute. The NoSQL Web API doesn't attach any special significance to such key user attributes, but to work with a structured-data API you must define the required attributes, set their values according to the value of the item's primary key (name) — which is composed of a sharding key and optionally also a sorting key — and refrain from modifying the values of these attributes. See also Sharding and Sorting Keys.
If the update or alternate-update expression is an empty string, the item will be created if it doesn't already exist, but no user attributes will be added or modified (other than adding a primary-key attribute for a new item if the Key parameter is set in the request body), and the request will complete successfully (HTTP status code 200).

Type: String

Requirement: Required

AlternateUpdateExpression

An alternate update expression that specifies the changes to make to the item's attributes when a condition expression, defined in the ConditionExpression request parameter, evaluates to false; (i.e., this parameter defines the else clause of a conditional if-then-else update expression). See Update Expression for syntax details and examples. When the alternate update expression is executed, it's evaluated against the table item to be updated, if it exists. If the item doesn't exist, the update creates it (as well as the parent table if it doesn't exist). See also the UpdateExpression notes, which apply to the alternate update expression as well.

Type: String

Requirement: Optional

ConditionExpression

A Boolean condition expression that defines a conditional logic for executing the update operation. See Condition Expression for syntax details and examples. The condition expression is evaluated against the table item to be updated, if it exists. Note:

If the condition expression evaluates to true — including in the case of an empty condition-expression string — the update expression that's assigned to the UpdateExpression request parameter is executed.
If the condition expression evaluates to false — including when the expression references a non-existing item attribute — the alternate update expression that's assigned to the AlternateUpdateExpression parameter is executed; if no alternate update expression is provided, the operation completes successfully without an update.

Note

In v3.6.1, when ConditionExpression evaluates to false, UpdateItem returns a 400 error even though the operation is considered successful.

Type: String

Requirement: Optional

Response

Response Data

None

Examples

Example 1 — a Basic Update Expression

Request

For a "MySupermarket" table in the "mycontainer" container, set the value of the manager attribute of the item named "beverages" to "Jackson S."; if the attribute exists, overwrite its current value, and if it doesn't exist create it. Add an expenses attribute with the value 0 only if the item doesn't already have such an attribute; (if the attribute exists, it will be reassigned its current value). If the item or table don't exist, create them and assign the item the specified update-attribute values.

POST /mycontainer/ HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: UpdateItem
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

{
    "TableName":        "MySupermarket",
    "Key":              {"department": {"S": "beverages"}},
    "UpdateExpression": "SET manager='Jackson S.'; SET expenses = if_not_exists(expenses,0);"
}

import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "UpdateItem",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {
            "TableName":        "MySupermarket",
            "Key":              {"department": {"S": "beverages"}},
            "UpdateExpression":
            "SET manager='Jackson S.'; SET expenses = if_not_exists(expenses,0);"
          }

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Response

HTTP/1.1 200 OK
Content-Type: application/json

Example 2 — an If-Then Update Expression

For a "Cars" table in the "mycontainer" container, set the value of the Alarm attribute of the item named 321234 to "ON" if the item has a State attribute whose value is either "Broken" or "Attention". If the item doesn't have an Alarm attribute, create the attribute, provided the state condition is fulfilled. If the item or table don't exist, create them and assign the item the specified alarm attribute value.

Request

POST /mycontainer/Fleet/ HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: UpdateItem
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

{
    "TableName":            "Cars",
    "Key":                  {"carReg": {"N": "321234"}},
    "ConditionExpression":  "State IN ('Broken', 'Attention')",
    "UpdateExpression":     "SET Alarm='ON'"
}

import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/Fleet/"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "UpdateItem",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {
            "TableName":            "Cars",
            "Key":                  {"carReg": {"N": "321234"}},
            "ConditionExpression":  "State IN ('Broken', 'Attention')",
            "UpdateExpression":     "SET Alarm='ON'"
          }

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Response

HTTP/1.1 200 OK
Content-Type: application/json

Example 3 — an If-Then-Else Update Expression

For a "site1" table in a data directory in the "mycontainer" container, update attributes of the item named "13"; (the item path is set as part of the URL in the request header): if the value of the item's is_init attribute is true, increase the current values of its a, b, c, and d attributes by 1. Otherwise (i.e., if is_init is false or isn't defined, or if the item doesn't exist), initialize attributes a, b, c, and d to 0, 10, 0, and 120 (respectively) and set the value of the is_init attribute to true; if the item or table don't exist, create them.

Request

POST /mycontainer/data/site1/13 HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: UpdateItem
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

{
    "ConditionExpression":        "is_init==true",
    "UpdateExpression":           "a=a+1; b=b+1; c=c+1; d=d+1;",
    "AlternateUpdateExpression":  "a=0; b=10; c=0; d=120; is_init=true;"
}

import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/data/site1/13"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "UpdateItem",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {
            "ConditionExpression":        "is_init==true",
            "UpdateExpression":           "a=a+1; b=b+1; c=c+1; d=d+1;",
            "AlternateUpdateExpression":  "a=0; b=10; c=0; d=120; is_init=true;"
          }

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Response

HTTP/1.1 200 OK
Content-Type: application/json