Dynomate
Browse documentation

DynamoDB items

On this page11
  1. 1Get item
  2. 2Query
  3. 3Scan
  4. 4Put item
  5. 5Update item
  6. 6Delete item
  7. 7Batch get
  8. 8Batch write
  9. 9Write transaction
  10. 10Read transaction
  11. 11PartiQL statement

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

Get item

Reads one item by its primary key.

DNML 
[[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.

[[dynamodb.get]]

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

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

DNML 
[[dynamodb.query]]name = "Recent orders"tableArn = "arn:aws:dynamodb:ap-southeast-2:123456789012:table/Orders"keyConditionExpression = "accountId = :accountId"expressionAttributeValues = { ":accountId" = "account#42" }scanIndexForward = falselimit = 25maxPages = 4maxItems = 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:
DNML 
exclusiveStartKey = "${recent_orders.lastEvaluatedKey}"
[[dynamodb.query]]

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 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

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

DNML 
[[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 = 0totalSegments = 4maxPages = 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.
[[dynamodb.scan]]

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 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

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

DNML 
[[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.

For background, see PutItem with a condition.

[[dynamodb.put]] Sometimes destructive

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

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

DNML 
[[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.
[[dynamodb.update]] Destructive

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

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

DNML 
[[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.

[[dynamodb.delete]] Destructive

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

Reads many items from one table by their primary keys.

DNML 
[[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.
[[dynamodb.batchGet]]

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

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

DNML 
[[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.
[[dynamodb.batchWrite]] Destructive

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

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

DNML 
[[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.
[[dynamodb.transactWrite]] Destructive

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

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

DNML 
[[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.

[[dynamodb.transactGet]]

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

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

DNML 
[[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.
[[dynamodb.executeStatement]] Sometimes destructive

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