PutItem

POST v1/data/{project_id}/tables/{table_name}/put_item

Description

Adds or rewrites existing item in table. If item already exists and it is just replaced if no other option is specified. It also supports conditions what are applied before inserting/updating item. If condition passes the item is updated or inserted.

Conditions support

You can define list of conditions what should be checked before applying insert or update. You can evaluate if specific item attribute value is equal to given in request or check its existing. Please look at sample below where ForumName is a hash key and Subject is a range key.

{
    "item": {
        "ForumName": {
            "S": "MagnetoDB"
        },
        "Subject": {
            "S": "How do I update multiple items?"
        },
        "Message": {
            "S": "Message text"
        },
        "Read": {
            "S": "true"
        }
    },
    "expected": {
        "Message": {
            "value": {"S": "Message text"}
        },
        "Read": {
            "exists": true
        }
    }
}

Also you can check if item with given primary key exists in table at all. To do it, you have to build condition if hash key exists. Technically the items is queried by hash and range key (if range key is defined) and after that condition is applied, so adding range key to condition is useless and ValidationError will be rose.

Request Syntax

{
    "expected": {
        "string": {
            "exists": "boolean",
            "value": {
                "B": "blob",
                "BS": [
                    "blob"
                ],
                "N": "string",
                "NS": [
                    "string"
                ],
                "S": "string",
                "SS": [
                    "string"
                ]
            }
        }
    },
    "item": {
        "string": {
            "B": "blob",
            "BS": [
                "blob"
            ],
            "N": "string",
            "NS": [
                "string"
            ],
            "S": "string",
            "SS": [
                "string"
            ]
        }
    },
    "time_to_live": "number",
    "return_values": "string"
}

Request Parameters

item
A map of attribute name/value pairs, one for each attribute. Only the primary key attributes are required.
Type: String to Attributevalue object map
Required: Yes
expected
The conditional block for the PutItem operation.
Type: String to expected Attributevalue object map
Required: No
time_to_live
Defines time to live for item
Type: number
Valid values: 0 - MAX_NUMBER
Required: No
return_values
Use return_values if you want to get the item attributes as they appeared before they were updated.
Type: String
Valid values: NONE | ALL_OLD
Required: No

Response Syntax

{
    "attributes": {
        "string": {
            "B": "blob",
            "BS": [
                "blob"
            ],
            "N": "string",
            "NS": [
                "string"
            ],
            "S": "string",
            "SS": [
                "string"
            ]
        }
    }
}

Response Elements

attributes
The attribute values as they appeared before the PutiItem operation.
Type: String to attribute struct

Errors

BackendInteractionException
ClusterIsNotConnectedException
ConditionalCheckFailedException
ValidationError

Samples

Sample Request

{
    "item": {
        "LastPostDateTime": {
            "S": "201303190422"
        },
        "Tags": {
            "SS": ["Update", "Multiple items", "HelpMe"]
        },
        "ForumName": {
            "S": "MagnetoDB"
        },
        "Message": {
            "S": "I want to update multiple items."
        },
        "Subject": {
            "S": "How do I update multiple items?"
        },
        "LastPostedBy": {
            "S": "fred@example.com"
        }
    },
    "expected": {
        "ForumName": {
            "exists": false
        },
        "Subject": {
            "exists": false
        }
    },
    "return_values": "ALL_OLD"
}

Sample Response

{
    "attributes": {
        "ForumName": {
            "S": "MagnetoDB"
        },
        "LastPostDateTime": {
            "S": "201303190422"
        },
        "LastPostedBy": {
            "S": "fred@example.com"
        },
        "Message": {
            "S": "I want to update multiple items."
        },
        "Subject": {
            "S": "How do I update multiple items?"
        },
        "Tags": {
            "SS": ["HelpMe", "Multiple items", "Update"]
        }
    }
}