DynamoDB items

Item operations read and write DynamoDB items. They also accept the common keys.

Item values can be plain TOML or typed, for example { N = "19.99" }. See Typed values.
Enumerated values, for example "all-new", are lowercase and case-sensitive.

Get item `[[dynamodb.get]]`

Reads one item by its primary key.

[[dynamodb.get]]
name = "Load order"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
keyValues = { accountId = "account#42", orderId = "order#1049" }
consistentRead = true

The result has item, found and requestId. item is null if the item does not exist.

Keys

keyValues map Required: The primary key of the item: the partition key, and the sort key if the table has one. In the app: Key tab › Key
projectionExpression string: Sets the attributes that DynamoDB returns. Use #name placeholders for reserved or unusual attribute names. In the app: Output tab › Projection expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Output tab › Attribute name aliases
consistentRead boolean: Set to true for strongly consistent reads. The default is false, and you cannot use an expression. In the app: Key tab › Consistent read
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Query `[[dynamodb.query]]`

Reads the items that share a partition key in a table or index, across one or more pages.

[[dynamodb.query]]
name = "Recent orders"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
keyConditionExpression = "accountId = :accountId"
expressionAttributeValues = { ":accountId" = "account#42" }
scanIndexForward = false
limit = 25
maxPages = 4
maxItems = 50

The result has items, count, scannedCount, pages, lastEvaluatedKey and requestId.
lastEvaluatedKey is null if no pages remain. To continue, use it in a later operation:

exclusiveStartKey = "${recent_orders.lastEvaluatedKey}"

Keys

keyConditionExpression string Required: Selects items by partition key, with an optional sort key condition. In the app: Query tab › Key condition expression
filterExpression string: Removes items that do not match, after DynamoDB reads them. The removed items still use read capacity. In the app: Query tab › Filter expression
projectionExpression string: Sets the attributes that DynamoDB returns. Use #name placeholders for reserved or unusual attribute names. In the app: Output tab › Projection expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Query tab › Attribute name aliases
expressionAttributeValues map: Maps the :value placeholders in expressions to values, in plain or typed form. In the app: Query tab › Attribute value aliases
indexName string: Queries this secondary index instead of the base table. In the app: Query tab › Index name
limit integer: The maximum number of items that DynamoDB reads in each AWS call, before it applies a filter. In the app: Output tab › Limit per call
consistentRead boolean: Set to true for strongly consistent reads. The default is false, and you cannot use an expression. In the app: Query tab › Consistent read
scanIndexForward boolean: Set to false to return items in descending sort key order. The default, true, returns them in ascending order. In the app: Output tab › Scan index forward
exclusiveStartKey string or map: Where the read continues: a lastEvaluatedKey token from an earlier result, or a key map. In the app: Output tab › Start token or key
maxPages integer: The number of AWS calls to make, one for each page. The default is 1, and 0 reads all pages. In the app: Output tab › Maximum pages
maxItems integer: Dynomate stops when it has at least this many items, even if maxPages permits more pages. In the app: Output tab › Maximum items
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Scan `[[dynamodb.scan]]`

Reads all items in a table or index, with an optional filter and parallel segments.

[[dynamodb.scan]]
name = "Open orders segment 0"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
filterExpression = "#status = :open"
expressionAttributeNames = { "#status" = "status" }
expressionAttributeValues = { ":open" = "OPEN" }
segment = 0
totalSegments = 4
maxPages = 0

Scan has the same paging keys and result keys as Query.
To split a scan, add one operation for each segment, with the same totalSegments. The operations run one at a time, not in parallel.

Keys

filterExpression string: Removes items that do not match, after DynamoDB reads them. The removed items still use read capacity. In the app: Scan tab › Filter expression
projectionExpression string: Sets the attributes that DynamoDB returns. Use #name placeholders for reserved or unusual attribute names. In the app: Output tab › Projection expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Scan tab › Attribute name aliases
expressionAttributeValues map: Maps the :value placeholders in expressions to values, in plain or typed form. In the app: Scan tab › Attribute value aliases
indexName string: Scans this secondary index instead of the base table. In the app: Scan tab › Index name
limit integer: The maximum number of items that DynamoDB reads in each AWS call, before it applies a filter. In the app: Output tab › Limit per call
consistentRead boolean: Set to true for strongly consistent reads. The default is false, and you cannot use an expression. In the app: Scan tab › Consistent read
exclusiveStartKey string or map: Where the read continues: a lastEvaluatedKey token from an earlier result, or a key map. In the app: Output tab › Start token or key
maxPages integer: The number of AWS calls to make, one for each page. The default is 1, and 0 reads all pages. In the app: Output tab › Maximum pages
maxItems integer: Dynomate stops when it has at least this many items, even if maxPages permits more pages. In the app: Output tab › Maximum items
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity
segment integer: The zero-based number of the segment to read in a parallel scan. Use it with totalSegments. In the app: Execution tab › Segment
totalSegments integer: The number of segments in the full parallel scan. In the app: Execution tab › Total segments

Put item `[[dynamodb.put]]`

Writes a complete item. It replaces an existing item with the same key. Sometimes destructive

[[dynamodb.put]]
name = "Create order"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
conditionExpression = "attribute_not_exists(accountId)"

[dynamodb.put.item]
accountId = "account#42"
orderId = "order#1050"
status = "NEW"
total = { N = "19.99" }

The result has attributes and requestId. attributes is the replaced item if returnValues = "all-old", or null.

Keys

item map Required: The complete item to write, with its primary key, in plain or typed form. In the app: Item tab › Item
conditionExpression string: The write succeeds only if this condition is true for the existing item. A put with attribute_not_exists on the partition key never replaces an item. In the app: Item tab › Condition expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Item tab › Attribute name aliases
expressionAttributeValues map: Maps the :value placeholders in expressions to values, in plain or typed form. In the app: Item tab › Attribute value aliases
returnValues enum: "none" | "all-old": Set to "all-old" to return the replaced item. The default is "none". In the app: Output tab › Return values
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Update item `[[dynamodb.update]]`

Changes the attributes of one item with an update expression or with SET, REMOVE, ADD and DELETE clauses. Destructive

[[dynamodb.update]]
name = "Mark shipped"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
keyValues = { accountId = "account#42", orderId = "order#1049" }
setExpression = "#status = :shipped"
removeExpression = "pendingReason"
conditionExpression = "attribute_exists(orderId)"
expressionAttributeNames = { "#status" = "status" }
expressionAttributeValues = { ":shipped" = "SHIPPED" }
returnValues = "updated-new"

Use updateExpression or at least one clause key.
Dynomate joins the clauses in the order SET, REMOVE, ADD, DELETE, and adds each missing keyword.
The result has attributes and requestId.

Keys

keyValues map Required: The primary key of the item to update. In the app: Update tab › Key
updateExpression string: The full update expression, for example SET #s = :s REMOVE legacy. Do not use it with the clause keys. In the app: Update tab › Update expression
setExpression string: The SET clause, with or without the SET keyword. In the app: Update tab › SET clause
removeExpression string: The REMOVE clause, with or without the REMOVE keyword. In the app: Update tab › REMOVE clause
addExpression string: The ADD clause, with or without the ADD keyword. In the app: Update tab › ADD clause
deleteExpression string: The DELETE clause, which removes elements from a set. In the app: Update tab › DELETE clause
conditionExpression string: The write succeeds only if this condition is true for the existing item. In the app: Update tab › Condition expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Update tab › Attribute name aliases
expressionAttributeValues map: Maps the :value placeholders in expressions to values, in plain or typed form. In the app: Update tab › Attribute value aliases
returnValues enum: "none" | "all-old" | "updated-old" | "all-new" | "updated-new": The attributes to return, from before or after the update. The default is "all-new". In the app: Output tab › Return values
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Delete item `[[dynamodb.delete]]`

Deletes one item by its primary key, with an optional condition. Destructive

[[dynamodb.delete]]
name = "Remove draft"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
keyValues = { accountId = "account#42", orderId = "order#1050" }
conditionExpression = "#status = :draft"
expressionAttributeNames = { "#status" = "status" }
expressionAttributeValues = { ":draft" = "DRAFT" }
returnValues = "all-old"

The result has attributes and requestId. attributes is the deleted item if returnValues = "all-old", or null.

Keys

keyValues map Required: The primary key of the item to delete. In the app: Key tab › Key
conditionExpression string: The delete succeeds only if this condition is true for the item. In the app: Key tab › Condition expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Key tab › Attribute name aliases
expressionAttributeValues map: Maps the :value placeholders in expressions to values, in plain or typed form. In the app: Key tab › Attribute value aliases
returnValues enum: "none" | "all-old": Set to "all-old" to return the deleted item. The default is "none". In the app: Output tab › Return values
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Batch get `[[dynamodb.batchGet]]`

Reads many items from one table by their primary keys.

[[dynamodb.batchGet]]
name = "Load orders"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
projectionExpression = "orderId, #status, total"
expressionAttributeNames = { "#status" = "status" }
keys = [
  { accountId = "account#42", orderId = "order#1049" },
  { accountId = "account#42", orderId = "order#1050" },
]

The result has items, count, unprocessedKeys and requestId.
Dynomate retries unprocessed keys a limited number of times. If keys remain, the operation fails with DNML_UNPROCESSED_ITEMS.

Keys

keys array of maps Required: The primary keys of the items to read, at least one. Dynomate splits a large list across more than one AWS call. In the app: Keys tab › Keys
projectionExpression string: Sets the attributes that DynamoDB returns. Use #name placeholders for reserved or unusual attribute names. In the app: Output tab › Projection expression
expressionAttributeNames map: Maps the #name placeholders in expressions to attribute names. In the app: Output tab › Attribute name aliases
consistentRead boolean: Set to true for strongly consistent reads. The default is false, and you cannot use an expression. In the app: Keys tab › Consistent read
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Batch write `[[dynamodb.batchWrite]]`

Puts and deletes many items in one table. The result has a status for each write. Destructive

[[dynamodb.batchWrite]]
name = "Archive drafts"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
puts = [
  { accountId = "account#42", orderId = "order#1051", status = "ARCHIVED" },
]
deletes = [
  { accountId = "account#42", orderId = "order#1050" },
]

Dynomate sends up to 25 writes in each AWS call.
The result has writeOutcomes, putCount, deleteCount and unprocessedCount.
writeOutcomes has one entry for each write, puts first. Each entry has kind, index, status and, if the write did not succeed, reason.
status is success, failed, skipped or unknown. skipped: Dynomate did not send the write. unknown: Dynomate sent it, but did not get a confirmation.
A failed batch also has writeOutcomes. Dynomate does not roll back. See No rollback.

Keys

puts array of maps: The complete items to write. You must give at least one put or delete. In the app: Writes tab › Items to put
deletes array of maps: The primary keys of the items to delete. You must give at least one put or delete. In the app: Writes tab › Keys to delete
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Write transaction `[[dynamodb.transactWrite]]`

Applies up to 100 puts, updates, deletes and condition checks in one all-or-nothing transaction. Destructive

[[dynamodb.transactWrite]]
name = "Reserve stock"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
actions = [
  {
    action = "put",
    item = { accountId = "account#42", orderId = "order#1052", status = "RESERVED" },
    conditionExpression = "attribute_not_exists(accountId)",
  },
  {
    action = "update",
    tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Inventory",
    keyValues = { sku = "sku#9" },
    updateExpression = "SET stock = stock - :one",
    conditionExpression = "stock >= :one",
    expressionAttributeValues = { ":one" = 1 },
  },
]

Each action needs the keys for its type:
- put: item.
- update: keyValues, and an update expression or clause keys.
- delete: keyValues.
- condition-check: keyValues and conditionExpression.
An action without tableArn uses the table of the operation.
An action can set returnValuesOnConditionCheckFailure to "none" or "all-old".
The result has actionCount and requestId.
If DynamoDB cancels the transaction, the operation fails with TransactionCanceledException. The error details give a reason for each action, in order.
For a full example, see transfer-order-ownership.

Keys

actions array of maps Required: From 1 to 100 actions that DynamoDB applies together or not at all. Each action is "put", "update", "delete" or "condition-check", and can set its own tableArn. In the app: Actions tab › Actions
clientRequestToken string: An idempotency token. Use the same token when you retry the same transaction. In the app: Execution tab › Client request token
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

Read transaction `[[dynamodb.transactGet]]`

Reads up to 100 items as one consistent snapshot, in the order of the gets.

[[dynamodb.transactGet]]
name = "Read order and stock"
tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"
gets = [
  { keyValues = { accountId = "account#42", orderId = "order#1052" } },
  {
    tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Inventory",
    keyValues = { sku = "sku#9" },
    projectionExpression = "stock",
  },
]

The result has items, count and requestId.

Keys

gets array of maps Required: From 1 to 100 reads, each with keyValues and optional projectionExpression, expressionAttributeNames and tableArn. The result keeps this order, with null for a missing item. In the app: Gets tab › Gets
returnConsumedCapacity enum: "none" | "total" | "indexes": Adds the consumed capacity to the result. The default is "none". In the app: Output tab › Consumed capacity

PartiQL statement `[[dynamodb.executeStatement]]`

Runs a PartiQL statement with positional parameters. The statement names the table. Sometimes destructive

[[dynamodb.executeStatement]]
name = "Shipped orders"
region = "ap-southeast-2"
statement = 'SELECT "orderId", "total" FROM "Orders" WHERE "accountId" = ? AND "status" = ?'
parameters = ["account#42", "SHIPPED"]
maxPages = 0

Dynomate treats a statement as destructive if its first word is not SELECT.
The result has items, count, pages, nextToken and requestId.
nextToken is null if no pages remain. To continue, use it in a later operation.

Keys

statement string Required: The PartiQL statement to run, with ? placeholders for the values in parameters. A statement that starts with SELECT is read-only. In the app: Statement tab › PartiQL statement
parameters array of values: The values for the ? placeholders, in order, in plain or typed form. In the app: Statement tab › Parameters
consistentRead boolean: Set to true for strongly consistent reads. The default is false, and you cannot use an expression. In the app: Statement tab › Consistent read
limit integer: The maximum number of items that DynamoDB reads in each AWS call. In the app: Output tab › Limit per call
nextToken string: Continues from the nextToken in an earlier result. In the app: Output tab › Next token
maxPages integer: The number of AWS calls to make, one for each page. The default is 1, and 0 reads all pages. In the app: Output tab › Maximum pages

DynamoDB items

Get item [[dynamodb.get]]

Keys

Query [[dynamodb.query]]

Keys

Scan [[dynamodb.scan]]

Keys

Put item [[dynamodb.put]]

Keys

Update item [[dynamodb.update]]

Keys

Delete item [[dynamodb.delete]]

Keys

Batch get [[dynamodb.batchGet]]

Keys

Batch write [[dynamodb.batchWrite]]

Keys

Write transaction [[dynamodb.transactWrite]]

Keys

Read transaction [[dynamodb.transactGet]]

Keys

PartiQL statement [[dynamodb.executeStatement]]

Keys

Get item `[[dynamodb.get]]`

Query `[[dynamodb.query]]`

Scan `[[dynamodb.scan]]`

Put item `[[dynamodb.put]]`

Update item `[[dynamodb.update]]`

Delete item `[[dynamodb.delete]]`

Batch get `[[dynamodb.batchGet]]`

Batch write `[[dynamodb.batchWrite]]`

Write transaction `[[dynamodb.transactWrite]]`

Read transaction `[[dynamodb.transactGet]]`

PartiQL statement `[[dynamodb.executeStatement]]`