Skip to content

Martini DynamoDB Functions

Overview

Martini's DynamoDB Functions, generated from DynamoDbMethods, let your workflows and services read, write, query, scan, and manage Amazon DynamoDB tables without writing AWS SDK code directly. Every function operates against a databaseConnectionName you register in Martini Runtime, so the same workflow or service logic works unchanged across your development, staging, and production DynamoDB connections.

What You Will Learn

  • How to read a single item with getItem, including its corrected description and full parameter list
  • How to query items efficiently with query, and when to reach for scanTable instead
  • How to write and remove items with putItem, updateItem, and deleteItem
  • Where to find batch, transactional, and table-management operations for more advanced scenarios

When To Use This

Use DynamoDB Functions when:

  • Your workflow or service needs to read, write, or delete items in a DynamoDB table by primary key
  • You need to find items matching a partition key (and optionally a sort key condition) with query, instead of reading every item in the table
  • You need to iterate over an entire table or secondary index with scanTable, including parallel scans
  • You need conditional writes, update expressions, or projection/filter expressions that a generic database node does not expose
  • You need batch or transactional operations across multiple items or tables, or PartiQL-based reads and writes
  • You need to create, update, describe, or list DynamoDB tables (including global tables) from a workflow or service, rather than through the AWS Console or CLI

Prerequisites

DynamoDB Functions Key Terms

The following terms describe parameters shared across most DynamoDB Functions.

Term Definition
databaseConnectionName The name of the DynamoDB connection registered in Martini Runtime that the function executes against. Required on every DynamoDB function.
tableName The name of the DynamoDB table the operation targets.
indexName The name of a secondary index to query or scan, instead of the table's primary index.
keys / keyModels A model array reference representing the primary key (partition key, and sort key if the table has one) of the item to get, update, or delete.
items A model array reference representing the attribute name/value pairs of an item to write with putItem.
expressionAttributeNames A map of substitution tokens for attribute names used inside an expression, useful when an attribute name collides with a DynamoDB reserved word.
expressionAttributeValues A model array reference of values that can be substituted inside a condition, filter, key condition, or update expression.
conditionExpression A condition that must evaluate to true for a conditional write (putItem, updateItem, deleteItem) to succeed.
keyConditionExpression The expression that specifies which partition key (and optionally sort key range) query evaluates.
filterExpression An expression DynamoDB applies to results after a query or scanTable operation, before returning them to Martini.
returnConsumedCapacity Controls how much detail about throughput consumption DynamoDB includes in the response (NONE, TOTAL, or INDEXES).
consistentRead Whether the read uses strongly consistent reads (true) or eventually consistent reads (false, the default DynamoDB behavior).

keys/keyModels, items, expressionAttributeValues/expressionAttributeValueModels, and exclusiveStartKeyModels are each a model array reference of io.toro.martini.dynamodb.MapAttributeValue, one entry per attribute name/value pair. The parameters accepted by partiQL are instead a model array reference of io.toro.martini.dynamodb.AttributeValue, one entry per positional PartiQL parameter.

Reading a Single Item with getItem

getItem returns the attributes for the item with the given primary key.

Getting Started

Using a Function Node or a Function Step, invoke getItem, supplying the required databaseConnectionName, tableName, and the primary key to read:

1
2
3
4
5
6
getItem(
    databaseConnectionName: 'dynamodb-orders',
    tableName: 'Orders',
    keys: [[key: 'orderId', value: [S: '42']]], 
    consistentRead: true
)

Expected result: the operation returns an output model reference containing a dynamodbOutput property, a model reference of io.toro.martini.dynamodb.DynamoDbResponse, holding the item's attributes when found, or an empty result when no item matches the given key.

Parameters

Property Required Description
databaseConnectionName Yes The name of the DynamoDB connection registered in Martini Runtime.
tableName Yes The name of the table to read from.
keys Yes A model array reference identifying the primary key of the item to retrieve.
consistentRead No Determines the read consistency model: true for strongly consistent reads, false for eventually consistent reads.
returnConsumedCapacity No Level of detail about throughput consumption returned in the response: NONE, TOTAL, or INDEXES.
projectionExpression No A string identifying one or more attributes to retrieve from the table, instead of every attribute.
expressionAttributeNames No Substitution tokens for attribute names referenced in projectionExpression.

Return Value

getItem returns an output model reference with a dynamodbOutput property, a model reference of io.toro.martini.dynamodb.DynamoDbResponse, exposing the retrieved item's attributes plus consumed-capacity details when returnConsumedCapacity is set.

Querying Items with query

query finds items based on primary key values, and is the most efficient way to retrieve a known set of items from a table or secondary index — prefer it over scanTable whenever you know the partition key you are looking for.

Getting Started

1
2
3
4
5
6
7
8
query(
    databaseConnectionName: 'dynamodb-orders',
    tableName: 'Orders',
    keyConditionExpression: 'customerId = :customerId',
    expressionAttributeValues: [[key: ':customerId', value: [S: 'cust-1001']]],
    scanIndexForward: false,
    limit: 20
)

Expected result: the operation returns the most recent 20 items whose customerId matches cust-1001, ordered by sort key descending (scanIndexForward: false).

Parameters

Property Required Description
databaseConnectionName Yes The name of the DynamoDB connection registered in Martini Runtime.
tableName Yes The name of the table to query.
indexName No The name of a secondary index to query, instead of the table's primary index.
select No The attributes to be returned in the result.
limit No The maximum number of items to evaluate.
consistentRead No Determines the read consistency model.
scanIndexForward No Whether to return results in ascending (true) or descending (false) sort-key order.
exclusiveStartKeyModels No The primary key of the first item that this operation evaluates, used to resume a paginated query.
returnConsumedCapacity No Level of detail about throughput consumption returned: NONE, INDEXES, or TOTAL.
projectionExpression No A string identifying one or more attributes to retrieve from matched items.
filterExpression No A string containing conditions that DynamoDB applies after the query, before returning results.
keyConditionExpression Yes The condition that specifies the partition key (and optional sort key range) to query.
expressionAttributeNames No Substitution tokens for attribute names referenced in an expression.
expressionAttributeValueModels No Values that can be substituted inside keyConditionExpression or filterExpression.

Return Value

query returns an output model reference with a dynamoDbQueryResponse property, a model reference of io.toro.martini.dynamodb.DynamoDbQueryResponse, containing the matched items, a pagination token (lastEvaluatedKey) when more results remain, and consumed-capacity details when requested.

Paginating query results

When a query's results exceed DynamoDB's response size limit, the response includes a lastEvaluatedKey. Pass that value into exclusiveStartKeyModels on a subsequent query call to retrieve the next page.

Scanning Tables with scanTable

scanTable returns one or more items by examining every item in a table or secondary index. Because a scan reads the entire table (or index), reserve it for cases where you cannot express the lookup as a query — for example, filtering on a non-key attribute across the whole dataset.

Parameters

Property Required Description
databaseConnectionName Yes The name of the DynamoDB connection registered in Martini Runtime.
tableName Yes The name of the table to scan.
indexName No The name of a secondary index to scan.
limit No The maximum number of items to evaluate.
select No The attributes to be returned in the result.
consistentRead No Determines the read consistency model during the scan.
exclusiveStartKeyModels No The primary key of the first item that this operation evaluates, used to resume a paginated scan.
returnConsumedCapacity No Level of detail about throughput consumption returned: NONE, INDEXES, or TOTAL.
projectionExpression No A string identifying one or more attributes to retrieve from the table.
filterExpression No A string containing conditions that DynamoDB applies after the scan, before returning results.
expressionAttributeNames No Substitution tokens for attribute names referenced in an expression.
expressionAttributeValueModels No Values that can be substituted inside filterExpression.
segment No Identifies an individual segment to be scanned by an application worker, for parallel scans.
totalSegments No The total number of segments a parallel scan is divided into.

Return Value

scanTable returns an output model reference with a dynamodbScanResponse property, also a model reference of io.toro.martini.dynamodb.DynamoDbQueryResponse — the same underlying type query uses, exposed under a different property name — containing the matched items, a pagination token when more results remain, and consumed-capacity details when requested.

Filtering happens after reading, not before

filterExpression is applied after DynamoDB reads the items covered by scanTable, so it does not reduce the read capacity consumed by the scan — it only reduces which items are returned to your workflow or service.

Writing Items with putItem and updateItem

putItem creates a new item, or replaces an existing item entirely. updateItem edits specific attributes of an existing item, or creates the item if it does not already exist — use updateItem when you want to change only some attributes without overwriting the whole item.

Parameters

Property Required Applies To Description
databaseConnectionName Yes Both The name of the DynamoDB connection registered in Martini Runtime.
tableName Yes Both The name of the table to write to.
items Yes putItem The attribute name/value pairs of the item to create or replace.
keyModels Yes updateItem The primary key of the item to update.
updateExpression No updateItem An expression that defines one or more attributes to update.
returnValues No Both Whether to return the item's attributes as they appeared before the write — see returnValues choices below.
returnConsumedCapacity No Both Level of detail about throughput consumption returned: NONE, TOTAL, or INDEXES.
returnItemCollectionMetrics No Both Whether item collection metrics are returned: NONE or SIZE.
conditionExpression No Both A condition that must be satisfied for the write to succeed.
expressionAttributeNames No Both Substitution tokens for attribute names referenced in an expression.
expressionAttributeValues No Both Values that can be substituted inside conditionExpression or updateExpression.

returnValues choices

Function Accepted values
putItem NONE, ALL_OLD
updateItem NONE, ALL_OLD, ALL_NEW, UPDATED_OLD, UPDATED_NEW

Return Value

Both putItem and updateItem return an output model reference with a dynamodbOutput property, a model reference of io.toro.martini.dynamodb.DynamoDbResponse — the same response shape used by getItem and deleteItem. The response includes the requested returnValues attributes and consumed-capacity details when requested.

Deleting Items with deleteItem

deleteItem removes a single item from a table by its primary key.

Property Required Description
databaseConnectionName Yes The name of the DynamoDB connection registered in Martini Runtime.
tableName Yes The name of the table to delete from.
keyModels Yes The primary key of the item to delete.
returnValues No Whether to return the item's attributes as they appeared before deletion: NONE or ALL_OLD.
returnConsumedCapacity No Level of detail about throughput consumption returned: NONE, TOTAL, or INDEXES.
returnItemCollectionMetrics No Whether item collection metrics are returned: NONE or SIZE.
conditionExpression No A condition that must be satisfied for the delete to succeed.
expressionAttributeNames No Substitution tokens for attribute names referenced in an expression.
expressionAttributeValueModels No Values that can be substituted inside conditionExpression.

deleteItem returns an output model reference with a dynamodbOutput property, a model reference of io.toro.martini.dynamodb.DynamoDbResponse — the same response shape used by getItem, putItem, and updateItem.

Performing Batch and Transactional Operations

Beyond single-item operations, DynamoDB Functions include batch and transactional operations for working with multiple items or tables in one call. Each still requires databaseConnectionName; the remaining parameters map directly to the equivalent AWS SDK request shape.

Function What It Does Output Property → Model Reference
batchGetItems(databaseConnectionName, returnConsumedCapacity, requestItems) Retrieves attributes of one or more items from one or more tables in a single call. batchGetItemResponse → io.toro.martini.dynamodb.BatchGetItemResponse
batchWriteItems(databaseConnectionName, models, returnConsumedCapacity, returnItemCollectionMetrics) Puts or deletes multiple items across one or more tables in a single call. batchWriteItemResponse → io.toro.martini.dynamodb.BatchWriteItemResponse
partiQL(databaseConnectionName, consistentRead, nextToken, statement, parameters) Performs a read or a singleton write using a PartiQL statement. partiQLResponse → io.toro.martini.dynamodb.PartiQLResponse
batchPartiQl(databaseConnectionName, statementRequests) Performs a batch of PartiQL reads or writes in a single call. statementResponse → a model array reference of io.toro.martini.dynamodb.StatementResponse
executeTransaction(databaseConnectionName, clientRequestToken, models) Performs transactional reads or writes using PartiQL statements. executeTransactionResponse → io.toro.martini.dynamodb.ExecuteTransactionResponse
transactGetItems(databaseConnectionName, returnConsumedCapacity, transactGetItemsRequest) Atomically retrieves multiple items from one or more tables in a single account and Region. transactGetItemResponse → io.toro.martini.dynamodb.TransactGetItemResponse
transactWriteItems(databaseConnectionName, returnConsumedCapacity, returnItemCollectionMetrics, clientRequestToken, transactWriteItemsRequest) Groups up to 100 write actions into a single all-or-nothing transaction. transactWriteItemResponses → io.toro.martini.dynamodb.TransactWriteItemResponses

For the meaning of PartiQL statements, transaction semantics, and batch request/response shapes, see the AWS DynamoDB PartiQL and Transactions documentation — the Martini parameters mirror the underlying AWS SDK request objects.

Managing Tables and Global Tables

DynamoDB Functions also cover table lifecycle management, so packages can provision or inspect tables as part of a deployment or setup workflow instead of relying solely on the AWS Console or CLI.

Function What It Does Output Property → Model Reference
createTable(databaseConnectionName, createTableRequest) Adds a new table to your account. createTableResponse → io.toro.martini.dynamodb.TableDescription
updateTable(databaseConnectionName, model) Modifies provisioned throughput, global secondary indexes, or DynamoDB Streams settings for a table. tableDescriptionResponse → io.toro.martini.dynamodb.TableDescription
describeTable(databaseConnectionName, tableName) Returns information about a table. Requires tableName. tableDescriptionResponse → io.toro.martini.dynamodb.TableDescription
deleteTable(databaseConnectionName, tableName) Deletes a table and all of its items. Requires tableName. tableDescriptionResponse → io.toro.martini.dynamodb.TableDescription
listTables(databaseConnectionName, limit, exclusiveStartTableName) Returns table names associated with the current account and endpoint. listTablesResponse → io.toro.martini.dynamodb.ListTablesResponse
createGlobalTable(databaseConnectionName, globalTableName, regionNames) Creates a global table from an existing table. Requires globalTableName. createGlobalTableResponse → io.toro.martini.dynamodb.GlobalTableDescription
updateGlobalTable(databaseConnectionName, globalTableName, models) Adds or removes replicas in a global table. updateGlobalTableResponse → io.toro.martini.dynamodb.GlobalTableDescription
describeGlobalTable(databaseConnectionName, globalTableName) Returns information about a global table. Requires globalTableName. describeGlobalTableResponse → io.toro.martini.dynamodb.GlobalTableDescription
listGlobalTables(databaseConnectionName, limit, exclusiveStartTableName, region) Lists global tables with a replica in the specified Region. listGlobalTablesResponse → io.toro.martini.dynamodb.ListGlobalTablesResponse

Legacy global tables

listGlobalTables, updateGlobalTable, createGlobalTable, and describeGlobalTable apply only to global tables Version 2017.11.29 (Legacy). AWS recommends Version 2019.11.21 (Current) for new global tables; consult the AWS Global Tables documentation to confirm which version applies to your table.

Troubleshooting DynamoDB Function Issues

Problem Cause Fix
A DynamoDB function does not appear in the Functions view You searched for a client-parameter overload, which is hidden from content assist as of Martini Runtime v2.8.0 Use the databaseConnectionName-based overload documented on this page instead
Designer flags databaseConnectionName or tableName as missing The value is required and was left blank Supply a valid, registered connection name and/or table name
query returns zero items unexpectedly keyConditionExpression references the wrong partition key attribute, or a required equality condition on the partition key is missing Ensure keyConditionExpression includes an equality condition on the partition key, optionally combined with a sort key condition
scanTable is slow or consumes excessive capacity The table is large and scanTable reads every item before applying filterExpression Use query instead if you can express the lookup by partition key, or use segment/totalSegments for a parallel scan
A conditional write fails silently conditionExpression evaluated to false for the targeted item Confirm the item's current attribute values satisfy conditionExpression before retrying

Helpful Resources