PutItem

On This Page

Description

Creates an item with the provided attributes. If an item with the same name (primary key) already exists in the specified table, the existing item is completely overwritten (replaced with a new item). If the item or table do not 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: PutItem
<Authorization OR X-v3io-session-key>: <value>

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

URL Resource Parameters

The path to the item to add. 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",
    "Item": {
        "string": {
            "S":     "string",
            "N":     "string",
            "BOOL":  Boolean,
            "B":     "blob"
        }
    }
}

payload = {
            "TableName": "string",
            "Key": {
                "string": {
                    "S": "string",
                    "N": "string"
                }
            },
            "ConditionExpression": "string",
            "Item": {
                "string": {
                    "S":    "string",
                    "N":    "string",
                    "BOOL": Boolean,
                    "B":    "blob"
                }
            }
          }

Parameters

TableName

The table (collection) to which the new item should be added — 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.

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 PutItem 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

ConditionExpression

A Boolean condition expression that defines a conditional logic for executing the put-item 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 item is created or overwritten (if it already exists).
If the condition expression evaluates to false — including when the expression references a non-existing item attribute — the operation completes successfully without creating or overwriting the item.

Note

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

Type: String

Requirement: Optional

Item

The item to add — an object containing zero or more attributes.

Note

As explained in the description of the Key parameter, when this parameter is set in the JSON request body, the platform defines a primary-key user attribute whose value is the item's name and primary-key value, which is also always stored in the item's __name system attribute. If you select to include in your request's Item object an attribute with the same name as specified in the Key parameter (even though this is redundant), make sure to set the value of this attribute to the same primary-key value as set in the Key parameter.
To access the table with Spark DataFrames or Presto, 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.

Type: An item JSON object that contains zero or more Attribute objects

Requirement: Required

Response

Response Data

None

Examples

Request

Add to the People table a person item with a primary-key ID attribute, and Name, Age, and Country attributes. If the item already exists, it will be entirely overwritten:

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

{
    "Key": {"ID": {"N": "1234"}},
    "Item": {
        "Age":     {"N": "42"},
        "Country": {"S": "UK"},
        "Name":    {"S": "John"}
    }
}

import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyDirectory/People/"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "PutItem",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {
            "Key": {"ID": {"N": "1234"}},
            "Item": {
                "Age":      {"N": "42"},
                "Country":  {"S": "UK"},
                "Name":     {"S": "John"}
            }
          }

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

Response

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