UpdateItem

When given a UpdateItem, the connection will return a UpdateItemResponse:

>>> connection(UpdateItem(table, {"h": 0}).remove("a"))
<LowVoltage.actions.update_item.UpdateItemResponse ...>

class UpdateItemResponse

The UpdateItem response.

attributes

The (previous or new) attributes of the item you just updated. If you used return_values_all_old(), return_values_all_new(), return_values_updated_old() or return_values_updated_new().

Type:None or dict

consumed_capacity

The capacity consumed by the request. If you used return_consumed_capacity_total() or return_consumed_capacity_indexes().

Type:None or ConsumedCapacity

item_collection_metrics

Metrics about the collection of the item you just updated. If a LSI was touched and you used return_item_collection_metrics_size().

Type:None or ItemCollectionMetrics

class UpdateItem(table_name=None, key=None)

The UpdateItem request.

Passing table_name to the constructor is like calling table_name() on the new instance. Passing key to the constructor is like calling key() on the new instance.

table_name(table_name)

Set TableName. Mandatory, can also be set in the constructor.

>>> connection(
...   UpdateItem(key={"h": 0})
...     .table_name(table)
...     .remove("a")
... )
<LowVoltage.actions.update_item.UpdateItemResponse ...>

key(key)

Set Key. Mandatory, can also be set in the constructor.

>>> connection(
...   UpdateItem(table_name=table)
...     .key({"h": 0})
...     .remove("a")
... )
<LowVoltage.actions.update_item.UpdateItemResponse ...>

set(attribute_name, value_name)

Add a value to SET as an attribute to UpdateExpression. As described in the developer guide.

>>> connection(PutItem(table, {"h": 0}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":forty_two")
...     .expression_attribute_value("forty_two", 42)
...     .return_values_all_new()
... ).attributes
{u'a': 42, u'h': 0}

remove(path)

Add an attribute to REMOVE to UpdateExpression. As described in the developer guide.

>>> connection(PutItem(table, {"h": 0, "a": 42}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .remove("a")
...     .return_values_all_new()
... ).attributes
{u'h': 0}

add(attribute_name, value_name)

Add a (set of) value(s) to ADD to a number (or a set) attribute to UpdateExpression. As described in the developer guide.

>>> connection(PutItem(table, {"h": 0, "a": 42}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .add("a", "two")
...     .expression_attribute_value("two", 2)
...     .return_values_all_new()
... ).attributes
{u'a': 44, u'h': 0}

>>> connection(PutItem(table, {"h": 0, "a": {2, 3}}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .add("a", "vals")
...     .expression_attribute_value("vals", {1, 2})
...     .return_values_all_new()
... ).attributes
{u'a': set([1, 2, 3]), u'h': 0}

delete(attribute_name, value_name)

Add a set of values to DELETE from a set attribute to UpdateExpression. As described in the developer guide.

>>> connection(PutItem(table, {"h": 0, "a": {1, 2, 3}}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .delete("a", "vals")
...     .expression_attribute_value("vals", {1, 2, 4})
...     .return_values_all_new()
... ).attributes
{u'a': set([3]), u'h': 0}

condition_expression(expression)

Set the ConditionExpression, making the request conditional. It will raise a ConditionalCheckFailedException if the condition is not met.

>>> connection(
...   UpdateItem(table, {"h": 1})
...     .remove("gh")
...     .condition_expression("#syn=:val")
...     .expression_attribute_name("syn", "gr")
...     .expression_attribute_value("val", 8)
... )
<LowVoltage.actions.update_item.UpdateItemResponse ...>

expression_attribute_name(synonym, name)

Add a synonym for an attribute name to ExpressionAttributeNames. Useful for attributes whose names don’t play well with ProjectionExpression, ConditionExpression or UpdateExpression because they contain a dot or brackets.

See condition_expression() for an example.

expression_attribute_value(name, value)

Add a named value to ExpressionAttributeValues.

See condition_expression() for an example.

return_consumed_capacity_indexes()

Set ReturnConsumedCapacity to INDEXES. The response will contain the capacity consumed by this request detailled on the table and the indexes.

>>> c = connection(
...   UpdateItem(table, {"h": 5}).set("gh", "h").set("gr", "h")
...     .return_consumed_capacity_indexes()
... ).consumed_capacity
>>> c.capacity_units
3.0
>>> c.table.capacity_units
1.0
>>> c.global_secondary_indexes["gsi"].capacity_units
2.0

return_consumed_capacity_total()

Set ReturnConsumedCapacity to TOTAL. The response will contain the total capacity consumed by this request.

>>> connection(
...   UpdateItem(table, {"h": 4}).set("gh", "h").set("gr", "h")
...     .return_consumed_capacity_total()
... ).consumed_capacity.capacity_units
3.0

return_consumed_capacity_none()

Set ReturnConsumedCapacity to NONE. The response will not contain the capacity consumed by this request.

>>> print connection(
...   UpdateItem(table, {"h": 6}).set("gh", "h").set("gr", "h")
...     .return_consumed_capacity_none()
... ).consumed_capacity
None

return_item_collection_metrics_size()

Set ReturnItemCollectionMetrics to SIZE. If the table has a local secondary index, the response will contain metrics about the size of item collections that were touched.

>>> m = connection(
...   UpdateItem(table2, {"h": 0, "r1": 0}).set("a", "h")
...     .return_item_collection_metrics_size()
... ).item_collection_metrics
>>> m.item_collection_key
{u'h': 0}
>>> m.size_estimate_range_gb
[0.0, 1.0]

return_item_collection_metrics_none()

Set ReturnItemCollectionMetrics to NONE. The response will not contain any item collection metrics.

>>> print connection(
...   UpdateItem(table2, {"h": 1, "r1": 0}).set("a", "h")
...     .return_item_collection_metrics_none()
... ).item_collection_metrics
None

return_values_all_old()

Set ReturnValues to ALL_OLD. The response will contain all the attributes of the item in its previous state.

>>> connection(PutItem(table, {"h": 0, "a": 1, "b": 2}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":v")
...     .expression_attribute_value("v", 2)
...     .return_values_all_old()
... ).attributes
{u'a': 1, u'h': 0, u'b': 2}

return_values_all_new()

Set ReturnValues to ALL_NEW. The response will contain all the attributes of the item in its new state.

>>> connection(PutItem(table, {"h": 0, "a": 1, "b": 2}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":v")
...     .expression_attribute_value("v", 2)
...     .return_values_all_new()
... ).attributes
{u'a': 2, u'h': 0, u'b': 2}

return_values_updated_old()

Set ReturnValues to UPDATED_OLD. The response will contain the just-updated attributes of the item in its previous state.

>>> connection(PutItem(table, {"h": 0, "a": 1, "b": 2}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":v")
...     .expression_attribute_value("v", 2)
...     .return_values_updated_old()
... ).attributes
{u'a': 1}

return_values_updated_new()

Set ReturnValues to UPDATED_NEW. The response will contain the just-updated attributes of the item in its new state.

>>> connection(PutItem(table, {"h": 0, "a": 1, "b": 2}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":v")
...     .expression_attribute_value("v", 2)
...     .return_values_updated_new()
... ).attributes
{u'a': 2}

return_values_none()

Set ReturnValues to NONE. The response will not include the attributes of the item.

>>> connection(PutItem(table, {"h": 0, "a": 1, "b": 2}))
<LowVoltage.actions.put_item.PutItemResponse ...>
>>> print connection(
...   UpdateItem(table, {"h": 0})
...     .set("a", ":v")
...     .expression_attribute_value("v", 2)
...     .return_values_none()
... ).attributes
None