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
      • 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.5.5, 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