Aws-cli: "aws dynamodb put-item help", no examples, totally unusable docs

[tat]

I spent two hours trying to run a simple put with a conditional expression and give up. expression-attribute-values gives an syntax error even using the example value provided in the doc.

It really needs some working examples.

[kyleknap]

Could you provide more detail or an example of the condition expression you are trying to use? I would be happy to help you figure it out.

As to the example provides in the doc that is giving you a syntax error, can you point me to the example that you are having issues with?

In the meantime, we will work on adding more examples for the put-item command.

[tat]

Hi Kyle,

I created a table to dispatch jobs to multiple boxes and I was trying to set a field atomically so that just one box would be able to succeed updating the job row; without the conditional part this is the command I run:

aws dynamodb put-item --table-name mytable --item '{ "jobid": { "S": "do_something" }, "lastrun": {"S": "201412250053"}, "lastworker":{"S": "1.2.3.4"} }'

I was trying to add a conditional expression to make the above command equivalent to something like:

update mytable set jobid=do_something,lastrun=TODAYDATE,lastworker=5.6.7.8
where jobid='do_something' and lastrun=201412250053;

I didn't find a way to make it work using --condition-expression.

The example giving me a syntax error was the one for --expression-attribute-names; for example adding this to the above command:
--expression-attribute-values '{ "a":{"S":"Available"}, "b":{"S":"Backordered"}, "d":{"S":"Discontinued"} }' --condition-expression "1=1"

Thanks for your help.

[kyleknap]

Alright here are some steps that you can follow:

Here is the table that I begin with:

$ aws dynamodb create-table --table-name MyJobs \
--attribute-definitions AttributeName=jobid,AttributeType=S \
--key-schema AttributeName=jobid,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

{
    "TableDescription": {
        "AttributeDefinitions": [
            {
                "AttributeName": "jobid", 
                "AttributeType": "S"
            }
        ], 
        "ProvisionedThroughput": {
            "NumberOfDecreasesToday": 0, 
            "WriteCapacityUnits": 1, 
            "ReadCapacityUnits": 1
        }, 
        "TableSizeBytes": 0, 
        "TableName": "MyJobs", 
        "TableStatus": "CREATING", 
        "KeySchema": [
            {
                "KeyType": "HASH", 
                "AttributeName": "jobid"
            }
        ], 
        "ItemCount": 0, 
        "CreationDateTime": 1419961278.246
    }
}

Step 1) Add an item to the table:

$ aws dynamodb put-item --table-name MyJobs \
--item '{ "jobid": { "S": "do_something" }, "lastrun": {"S": "201412250053"}, "lastworker":{"S": "1.2.3.4"} }'

Step 2) Check the item it is in the table:

$ aws dynamodb scan --table-name MyJobs

{
    "Count": 1, 
    "Items": [
        {
            "lastworker": {
                "S": "1.2.3.4"
            }, 
            "lastrun": {
                "S": "201412250053"
            }, 
            "jobid": {
                "S": "do_something"
            }
        }
    ], 
    "ScannedCount": 1, 
    "ConsumedCapacity": null
}

Step 3) Try to do update via a failing condition expression (An error is appropriately thrown):

$ aws dynamodb put-item --table-name MyJobs \
--item '{ "jobid": { "S": "do_something" }, "lastrun": {"S": "201412300053"}, "lastworker":{"S": "5.6.7.8"} }'  \
--condition-expression "jobid=:ji AND lastrun=:lr"  \
--expression-attribute-value '{":ji": {"S": "do_something"}, ":lr": {"S": "2"}}'

A client error (ConditionalCheckFailedException) occurred when calling the PutItem operation: The conditional request failed

4) Try to update with a successful condition expression:

$ aws dynamodb put-item --table-name MyJobs \
--item '{ "jobid": { "S": "do_something" }, "lastrun": {"S": "201412300053"}, "lastworker":{"S": "5.6.7.8"} }'  \
--condition-expression "jobid=:ji AND lastrun=:lr" \
--expression-attribute-value '{":ji": {"S": "do_something"}, ":lr": {"S": "201412250053"}}'

5) Ensure the object was updated:

$ aws dynamodb scan --table-name MyJobs

{
    "Count": 1, 
    "Items": [
        {
            "lastworker": {
                "S": "5.6.7.8"
            }, 
            "lastrun": {
                "S": "201412300053"
            }, 
            "jobid": {
                "S": "do_something"
            }
        }
    ], 
    "ScannedCount": 1, 
    "ConsumedCapacity": null
}

Let me know if this works for you or if you need any more help.

As to the issue with the example, it looks like the keys in --example-attribute-values all need colons prepending them. And we are looking into updating and adding more examples as well.

[tat]

Thanks Kyle that's very helpful.

From your examples it looks like all values going in the --conditional-expression argument must be previously mapped with --expression-attribute-value and that using simple values is not supported, right?

I mean something like
--condition-expression "jobid='do_something' AND lastrun='12341234' "

[kyleknap]

Yeah, you need to use expression attribute values if you are going to use a condition expression based on an attribute's value.

There are some examples for the other AWS SDK's and they do it the same way as well. Like here is an example for the AWS Java SDK:
http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/JavaDocumentAPIItemCRUD.html#PutDocumentAPIJava

[tat]

Thanks

[kyleknap]

Just taking note of another example that would be useful to add based on conversation with another CLI user:

This example does a conditional put on if the item exists:

$ aws dynamodb put-item --table-name MyJobs --item '{"jobid":{"S":"do_something"}}' --condition-expression "attribute_not_exists(jobid)"

If you were following along with the previous examples that I have provided, that should fail because the item already exists.

[viper25]

I second this, there needs to be some real examples for DynamoDB documentation. I;m pretty no one who's new to the DynamoDB API will get this on the first go. It'd be just enough if what's listed in this response would be added to the official documentation.

[justnance]

@tat and @viper25 - Our documentation has been updated with examples since this issue was created. Please take a look and let us know what you think. Thanks for your patience.

https://docs.aws.amazon.com/cli/latest/reference/dynamodb/put-item.html
https://docs.aws.amazon.com/cli/latest/userguide/cli-services-dynamodb.html
https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html

[tat]

Thanks!