DynamoDB Client vs. Document Client
This is 3 years old. I have left it up because the reasoning still holds, but check the library docs before trusting the code.
DynamoDB gives you two ways to talk to it from Node, and the difference between them is entirely about who owns the shape of your data.
The low-level client
The DynamoDB client speaks DynamoDB's own wire format. Every attribute is tagged with its
type, so a string is { S: 'value' } and a number is { N: '42' } — a string, notably, even
though it is a number. You are writing the type map yourself.
await dynamodb.putItem({
TableName: 'users',
Item: {
id: { S: 'user-1' },
name: { S: 'Juan' },
visits: { N: '42' },
},
})The Document Client
The DocumentClient wraps that and marshals plain JavaScript objects for you. You write the
object you actually have, and it handles the tagging on the way in and the untagging on the
way out.
await documentClient.put({
TableName: 'users',
Item: { id: 'user-1', name: 'Juan', visits: 42 },
})Which one
Most application code wants the Document Client. You reach for the raw client when you need control the marshaller takes away from you — precise numeric handling where JavaScript's number type would lose you something, or working with an attribute whose type you are deciding at runtime.
The mistake worth avoiding is mixing them against the same table in the same codebase without noticing. The shape you read back depends on which one you used to write, and that is a confusing afternoon.