What represents multiple related request items grouped together as one request

I believe that another correct way to approach this would be to create another resource that represents your collection of resources. Example, imagine that we have an endpoint like /api/sheep/{id} and we can POST to /api/sheep to create a sheep resource.

Now, if we want to support bulk creation, we should consider a new flock resource at /api/flock (or /api/-collection if you lack a better meaningful name). Remember that resources don't need to map to your database or app models. This is a common misconception.

Resources are a higher level representation, unrelated with your data. Operating on a resource can have significant side effects, like firing an alert to a user, updating other related data, initiating a long lived process, etc. For example, we could map a file system or even the unix ps command as a REST API.

I think it is safe to assume that operating a resource may also mean to create several other entities as a side effect.

In Amazon DynamoDB, an item is a collection of attributes. Each attribute has a name and a value. An attribute value can be a scalar, a set, or a document type. For more information, see Amazon DynamoDB: How it works.

DynamoDB provides four operations for basic create, read, update, and delete (CRUD) functionality. All these operations are atomic.

  • aws dynamodb get-item \
        --table-name ProductCatalog \
        --key '{"Id":{"N":"1"}}' \
        --consistent-read \
        --projection-expression "Description, Price, RelatedItems" \
        --return-consumed-capacity TOTAL
    9 — Create an item.

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    0 — Read an item.

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    1 — Update an item.

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    2 — Delete an item.

Each of these operations requires that you specify the primary key of the item that you want to work with. For example, to read an item using

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0, you must specify the partition key and sort key (if applicable) for that item.

In addition to the four basic CRUD operations, DynamoDB also provides the following:

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    4 — Read up to 100 items from one or more tables.

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    5 — Create or delete up to 25 items in one or more tables.

These batch operations combine multiple CRUD operations into a single request. In addition, the batch operations read and write items in parallel to minimize response latencies.

This section describes how to use these operations and includes related topics, such as conditional updates and atomic counters. This section also includes example code that uses the AWS SDKs.

Reading an item

To read an item from a DynamoDB table, use the

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 operation. You must provide the name of the table, along with the primary key of the item you want.

Example

The following AWS CLI example shows how to read an item from the

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
7 table.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}'

With

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0, you must specify the entire primary key, not just part of it. For example, if a table has a composite primary key (partition key and sort key), you must supply a value for the partition key and a value for the sort key.

A

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 request performs an eventually consistent read by default. You can use the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}
0 parameter to request a strongly consistent read instead. (This consumes additional read capacity units, but it returns the most up-to-date version of the item.)

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 returns all of the item's attributes. You can use a projection expression to return only some of the attributes. For more information, see Projection expressions.

To return the number of read capacity units consumed by

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0, set the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}
3 parameter to
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}
4.

Example

The following AWS Command Line Interface (AWS CLI) example shows some of the optional

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 parameters.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL

Writing an item

To create, update, or delete an item in a DynamoDB table, use one of the following operations:

  • aws dynamodb get-item \
        --table-name ProductCatalog \
        --key '{"Id":{"N":"1"}}' \
        --consistent-read \
        --projection-expression "Description, Price, RelatedItems" \
        --return-consumed-capacity TOTAL
    9

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    1

  • aws dynamodb put-item \
        --table-name Thread \
        --item file://item.json
    2

For each of these operations, you must specify the entire primary key, not just part of it. For example, if a table has a composite primary key (partition key and sort key), you must provide a value for the partition key and a value for the sort key.

To return the number of write capacity units consumed by any of these operations, set the

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}
3 parameter to one of the following:

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"},
        "Message": {"S": "First post in this thread"},
        "LastPostedBy": {"S": "[email protected]"},
        "LastPostDateTime": {"S": "201603190422"}
    }
    4 — Returns the total number of write capacity units consumed.

  • aws dynamodb update-item \
        --table-name Thread \
        --key file://key.json \
        --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
        --expression-attribute-values file://expression-attribute-values.json \
        --return-values ALL_NEW
    1 — Returns the total number of write capacity units consumed, with subtotals for the table and any secondary indexes that were affected by the operation.

  • aws dynamodb update-item \
        --table-name Thread \
        --key file://key.json \
        --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
        --expression-attribute-values file://expression-attribute-values.json \
        --return-values ALL_NEW
    2 — No write capacity details are returned. (This is the default.)

PutItem

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9 creates a new item. If an item with the same key already exists in the table, it is replaced with the new item.

Example

Write a new item to the

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
4 table. The primary key for
aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
4 consists of
aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
6 (partition key) and
aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
7 (sort key).

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json

The arguments for

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
8 are stored in the
aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
9 file.

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}

If an item with the specified key does not exist,

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 creates a new item. Otherwise, it modifies an existing item's attributes.

You use an update expression to specify the attributes that you want to modify and their new values. For more information, see Update expressions.

Within the update expression, you use expression attribute values as placeholders for the actual values. For more information, see Expression attribute values.

Example

Modify various attributes in the

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
4 item. The optional
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
2 parameter shows the item as it appears after the update. For more information, see Return values.

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW

The arguments for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
3 are stored in the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
4 file.

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}

The arguments for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
5 are stored in the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
6 file.

{
    ":zero": {"N":"0"},
    ":lastpostedby": {"S":"[email protected]"}
}

DeleteItem

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2 deletes the item with the specified key.

Example

The following AWS CLI example shows how to delete the

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
4 item.

aws dynamodb delete-item \
    --table-name Thread \
    --key file://key.json

Return values

In some cases, you might want DynamoDB to return certain attribute values as they appeared before or after you modified them. The

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1, and
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2 operations have a
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
2 parameter that you can use to return the attribute values before or after they are modified.

The default value for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
2 is
aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
2, meaning that DynamoDB does not return any information about attributes that were modified.

The following are the other valid settings for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
2, organized by DynamoDB API operation.

PutItem

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    {
        ":zero": {"N":"0"},
        ":lastpostedby": {"S":"[email protected]"}
    }
    7

    • If you overwrite an existing item,

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 returns the entire item as it appeared before the overwrite.

    • If you write a nonexistent item,

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 has no effect.

The most common usage for

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 is to update an existing item. However,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 actually performs an upsert, meaning that it automatically creates the item if it doesn't already exist.

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    {
        ":zero": {"N":"0"},
        ":lastpostedby": {"S":"[email protected]"}
    }
    7

    • If you update an existing item,

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 returns the entire item as it appeared before the update.

    • If you update a nonexistent item (upsert),

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 has no effect.

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    aws dynamodb delete-item \
        --table-name Thread \
        --key file://key.json
    7

    • If you update an existing item,

      aws dynamodb delete-item \
          --table-name Thread \
          --key file://key.json
      7 returns the entire item as it appeared after the update.

    • If you update a nonexistent item (upsert),

      aws dynamodb delete-item \
          --table-name Thread \
          --key file://key.json
      7 returns the entire item.

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    aws dynamodb batch-get-item \
        --request-items file://request-items.json
    1

    • If you update an existing item,

      aws dynamodb batch-get-item \
          --request-items file://request-items.json
      1 returns only the updated attributes, as they appeared before the update.

    • If you update a nonexistent item (upsert),

      aws dynamodb batch-get-item \
          --request-items file://request-items.json
      1 has no effect.

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    aws dynamodb batch-get-item \
        --request-items file://request-items.json
    5

    • If you update an existing item,

      aws dynamodb batch-get-item \
          --request-items file://request-items.json
      5 returns only the affected attributes, as they appeared after the update.

    • If you update a nonexistent item (upsert),

      aws dynamodb batch-get-item \
          --request-items file://request-items.json
      5 returns only the updated attributes, as they appear after the update.

DeleteItem

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"}
    }
    2:
    {
        ":zero": {"N":"0"},
        ":lastpostedby": {"S":"[email protected]"}
    }
    7

    • If you delete an existing item,

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 returns the entire item as it appeared before you deleted it.

    • If you delete a nonexistent item,

      {
          ":zero": {"N":"0"},
          ":lastpostedby": {"S":"[email protected]"}
      }
      7 doesn't return any data.

Batch operations

For applications that need to read or write multiple items, DynamoDB provides the

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 and
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
5 operations. Using these operations can reduce the number of network round trips from your application to DynamoDB. In addition, DynamoDB performs the individual read or write operations in parallel. Your applications benefit from this parallelism without having to manage concurrency or threading.

The batch operations are essentially wrappers around multiple read or write requests. For example, if a

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 request contains five items, DynamoDB performs five
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 operations on your behalf. Similarly, if a
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
5 request contains two put requests and four delete requests, DynamoDB performs two
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9 and four
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2 requests.

In general, a batch operation does not fail unless all the requests in the batch fail. For example, suppose that you perform a

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 operation, but one of the individual
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 requests in the batch fails. In this case,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 returns the keys and data from the
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 request that failed. The other
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 requests in the batch are not affected.

BatchGetItem

A single

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 operation can contain up to 100 individual
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
0 requests and can retrieve up to 16 MB of data. In addition, a
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
4 operation can retrieve items from multiple tables.

Example

Retrieve two items from the

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW
4 table, using a projection expression to return only some of the attributes.

aws dynamodb batch-get-item \
    --request-items file://request-items.json

The arguments for

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
08 are stored in the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
09 file.

{
    "Thread": {
        "Keys": [
            {
                "ForumName":{"S": "Amazon DynamoDB"},
                "Subject":{"S": "DynamoDB Thread 1"}
            },
            {
                "ForumName":{"S": "Amazon S3"},
                "Subject":{"S": "S3 Thread 1"}
            }
        ],
        "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies"
    }
}

BatchWriteItem

The

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
5 operation can contain up to 25 individual
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9 and
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2 requests and can write up to 16 MB of data. (The maximum size of an individual item is 400 KB.) In addition, a
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
5 operation can put or delete items in multiple tables.

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
5 does not support
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 requests.

Example

Write two items to the

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
7 table.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
0

The arguments for

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
08 are stored in the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
09 file.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
1

Atomic counters

You can use the

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 operation to implement an atomic counter—a numeric attribute that is incremented, unconditionally, without interfering with other write requests. (All write requests are applied in the order in which they were received.) With an atomic counter, the updates are not idempotent. In other words, the numeric value increments each time you call
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1.

You might use an atomic counter to track the number of visitors to a website. In this case, your application would increment a numeric value, regardless of its current value. If an

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 operation fails, the application could simply retry the operation. This would risk updating the counter twice, but you could probably tolerate a slight overcounting or undercounting of website visitors.

An atomic counter would not be appropriate where overcounting or undercounting can't be tolerated (for example, in a banking application). In this case, it is safer to use a conditional update instead of an atomic counter.

For more information, see Incrementing and decrementing numeric attributes.

Example

The following AWS CLI example increments the

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 of a product by 5. (Because
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 is not idempotent, the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 increases every time you run this example.)

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
2

By default, the DynamoDB write operations (

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2) are unconditional: Each operation overwrites an existing item that has the specified primary key.

DynamoDB optionally supports conditional writes for these operations. A conditional write succeeds only if the item attributes meet one or more expected conditions. Otherwise, it returns an error. Conditional writes are helpful in many situations. For example, you might want a

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9 operation to succeed only if there is not already an item with the same primary key. Or you could prevent an
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 operation from modifying an item if one of its attributes has a certain value.

Conditional writes are helpful in cases where multiple users attempt to modify the same item. Consider the following diagram, in which two users (Alice and Bob) are working with the same item from a DynamoDB table.

What represents multiple related request items grouped together as one request

Suppose that Alice uses the AWS CLI to update the

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 attribute to 8.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
3

The arguments for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
5 are stored in the file
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
6:

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
4

Now suppose that Bob issues a similar

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 request later, but changes the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 to 12. For Bob, the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
5 parameter looks like the following.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
5

Bob's request succeeds, but Alice's earlier update is lost.

To request a conditional

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
9,
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
2, or
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1, you specify a condition expression. A condition expression is a string containing attribute names, conditional operators, and built-in functions. The entire expression must evaluate to true. Otherwise, the operation fails.

Now consider the following diagram, showing how conditional writes would prevent Alice's update from being overwritten.

What represents multiple related request items grouped together as one request

Alice first tries to update

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 to 8, but only if the current
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 is 10.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
6

The arguments for

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
5 are stored in the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
6 file.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
7

Alice's update succeeds because the condition evaluates to true.

Next, Bob attempts to update the

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 to 12, but only if the current
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 is 10. For Bob, the
{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}
5 parameter looks like the following.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
8

Because Alice has previously changed the

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 to 8, the condition expression evaluates to false, and Bob's update fails.

For more information, see Condition expressions.

Conditional write idempotence

Conditional writes can be idempotent if the conditional check is on the same attribute that is being updated. This means that DynamoDB performs a given write request only if certain attribute values in the item match what you expect them to be at the time of the request.

For example, suppose that you issue an

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 request to increase the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 of an item by 3, but only if the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 is currently 20. After you send the request, but before you get the results back, a network error occurs, and you don't know whether the request was successful. Because this conditional write is idempotent, you can retry the same
aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json
1 request, and DynamoDB updates the item only if the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
22 is currently 20.

Capacity units consumed by conditional writes

If a

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
52 evaluates to false during a conditional write, DynamoDB still consumes write capacity from the table:

  • If the item does not currently exist in the table, DynamoDB consumes one write capacity unit.

  • If the item does exist, the number of write capacity units consumed depends on the size of the item. For example, a failed conditional write of a 1 KB item would consume one write capacity unit. If the item were twice that size, the failed conditional write would consume two write capacity units.

Write operations consume write capacity units only. They never consume read capacity units.

A failed conditional write returns a

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
53. When this occurs, you don't receive any information in the response about the write capacity that was consumed. However, you can view the
aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL
54 metric for the table in Amazon CloudWatch. For more information, see DynamoDB metrics in Logging and monitoring in DynamoDB.

To return the number of write capacity units consumed during a conditional write, you use the

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[email protected]"},
    "LastPostDateTime": {"S": "201603190422"}
}
3 parameter:

  • {
        "ForumName": {"S": "Amazon DynamoDB"},
        "Subject": {"S": "New discussion thread"},
        "Message": {"S": "First post in this thread"},
        "LastPostedBy": {"S": "[email protected]"},
        "LastPostDateTime": {"S": "201603190422"}
    }
    4 — Returns the total number of write capacity units consumed.

  • aws dynamodb update-item \
        --table-name Thread \
        --key file://key.json \
        --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
        --expression-attribute-values file://expression-attribute-values.json \
        --return-values ALL_NEW
    1 — Returns the total number of write capacity units consumed, with subtotals for the table and any secondary indexes that were affected by the operation.

  • aws dynamodb update-item \
        --table-name Thread \
        --key file://key.json \
        --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
        --expression-attribute-values file://expression-attribute-values.json \
        --return-values ALL_NEW
    2 — No write capacity details are returned. (This is the default.)

Unlike a global secondary index, a local secondary index shares its provisioned throughput capacity with its table. Read and write activity on a local secondary index consumes provisioned throughput capacity from the table.

An order guide represents multiple related request items grouped together as one request.

What is the difference between order guide and catalog item in ServiceNow?

2. The main difference between a catalog item and an order guide is what happens after you submit them. A catalog item works with the cart where you can add multiple and then checkout. On the back end it creates a request, request item, and possibly approvals and tasks depending on its workflow.

What is an order guide?

An order guide submits a single service catalog request that generates several items. Order guides allow you to define rules that identify which catalog items to include in a request. This can be extremely useful in the (obvious) use case of user onboarding.

What is the difference between service catalog and record producer in ServiceNow?

The service catalog is a collection of request forms presented as Catalog Items, Record Prodcures, Content Items, Order Guides, etc. A record producer is a nice front end you can include in your Service Catalog to create records. Ask user friendly questions instead of using field labels on a standard form.