Cameleer

AWS DynamoDB component

The aws2-ddb component writes, reads, queries, scans and deletes items in Amazon DynamoDB tables, using plain maps instead of DynamoDB attribute values.

Scheme: aws2-ddb: · Crate: cameleer-cloud · Cargo feature: cloud · Consumer: no · Producer: yes · Apache Camel: AWS DynamoDB

When to use it

  • Store orders, device state or session data from a route.
  • Look up an item by key to enrich a message.
  • Keep the memory of an AI agent (conversation state keyed by session id) in a serverless table.

For change data capture on a table, use aws2-ddbstream.

URI format

text
aws2-ddb://tableName[?options]

Example

Save each JSON order from a queue as an item:

yaml example: aws2-ddb-save-order
- route:
    id: save-orders
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAwsDdbItem
            simple: "${body}"
        - to: "aws2-ddb://orders?region={{env:AWS_REGION:us-east-1}}&operation=PutItem"
        - log: "saved order ${header.CamelAwsDdbItem[orderId]}"

Items, keys and conditions are plain maps. Strings become S, numbers N, booleans BOOL, null NULL, bytes B, lists L and maps M; results are converted back the same way.

Rust DSL

rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}")
        .unmarshal("json")
        .set_header("CamelAwsDdbItem", simple("${body}"))
        .to("aws2-ddb://orders?region={{env:AWS_REGION:us-east-1}}&operation=PutItem")
        .log("saved order ${header.CamelAwsDdbItem[orderId]}");
})?;

Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in Cloud credentials.

optiondefaultdescription
operationPutItemPutItem, GetItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItems, DescribeTable, UpdateTable, DeleteTable. The CamelAwsDdbOperation header overrides it.
consistentReadfalseStrongly consistent reads.
enabledInitialDescribeTabletrueDescribe the table when the endpoint starts.
keyAttributeNameWhen set and the table is missing at start, create it with this hash key.
keyAttributeTypeSType of the created hash key.
readCapacity, writeCapacity1Provisioned throughput of the created table.

Message headers

headerdirectiondescription
CamelAwsDdbIteminItem of PutItem (map).
CamelAwsDdbKeyinKey of GetItem, UpdateItem, DeleteItem (map).
CamelAwsDdbUpdateValuesinUpdateItem: attribute to new value (null deletes).
CamelAwsDdbUpdateExpression, CamelAwsDdbConditionExpression, CamelAwsDdbKeyConditionExpression, CamelAwsDdbFilterExpression, CamelAwsDdbProjectionExpressioninExpressions.
CamelAwsDdbExpressionAttributeNames, CamelAwsDdbExpressionAttributeValuesin#name and :value placeholders (plain values). CamelAwsDdbFilterExpressionAttributeNames / ...Values are accepted too.
CamelAwsDdbKeyConditions, CamelAwsDdbScanFilterinLegacy Query / Scan conditions.
CamelAwsDdbReturnValues, CamelAwsDdbConsistentRead, CamelAwsDdbAttributeNames, CamelAwsDdbIndexName, CamelAwsDdbLimit, CamelAwsDdbStartKey, CamelAwsDdbScanIndexForwardinRequest settings.
CamelAwsDdbBatchItemsinBatchGetItems: table to {Keys, ConsistentRead, ProjectionExpression}.
CamelAwsDdbReadCapacity, CamelAwsDdbWriteCapacity, CamelAwsDdbStreamViewTypeinUpdateTable (stream view type is a Cameleer extension).
CamelAwsDdbTableName, CamelAwsDdbOperationinOverride the table and the operation.
CamelAwsDdbAttributes, CamelAwsDdbItems, CamelAwsDdbCount, CamelAwsDdbScannedCount, CamelAwsDdbLastEvaluatedKeyoutResults.
CamelAwsDdbBatchResponse, CamelAwsDdbUnprocessedKeysoutBatchGetItems results.
CamelAwsDdbTableStatus, CamelAwsDdbItemCount, CamelAwsDdbKeySchema, CamelAwsDdbProvisionedThroughput, CamelAwsDdbStreamArnoutTable information.

Run it with Docker

sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml

Common questions

How do I read an item by key?

Set CamelAwsDdbKey to a map such as {"orderId": "o-1001"} and use operation=GetItem; the item is returned in the CamelAwsDdbAttributes header.

How do I increment a counter?

Use UpdateItem with CamelAwsDdbUpdateExpression = SET hits = hits + :one and CamelAwsDdbExpressionAttributeValues = {":one": 1}.

Does it work with DynamoDB Local?

Yes: uriEndpointOverride=http://localhost:8000&overrideEndpoint=true.

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.

Edit this page on GitHub