47

I want to know the difference between the AWS SDK DynamoDB client and the DynamoDB DocumentClient? In which use case should we use the DynamoDB client over the DocumentClient? 

const dynamoClient = new AWS.DynamoDB.DocumentClient();

vs 

const dynamo = new AWS.DynamoDB();
jarmod
  • 71,565
  • 16
  • 115
  • 122
Thiwanka Wickramage
  • 782
  • 1
  • 10
  • 22

3 Answers3

46

I think this can be best answered by comparing two code samples which do the same thing.

Here's how you put an item using the dynamoDB client:

var params = {
    Item: {
        "AlbumTitle": {
            S: "Somewhat Famous"
        },
        "Artist": {
            S: "No One You Know"
        },
        "SongTitle": {
            S: "Call Me Today"
        }
    },
    TableName: "Music"
};
dynamodb.putItem(params, function (err, data) {
    if (err) console.log(err)
    else console.log(data);           
});

Here's how you put the same item using the DocumentClient API:

var params = {
    Item: {
        "AlbumTitle": "Somewhat Famous",
        "Artist": "No One You Know",
        "SongTitle": "Call Me Today"
    },
    TableName: "Music"
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.put(params, function (err, data) {
    if (err) console.log(err);
    else console.log(data);
});

As you can see in the DocumentClient the Item is specified in a more natural way. Similar differences exist in all other operations that update DDB (update(), delete()) and in the items returned from read operations (get(), query(), scan()).

Itay Maman
  • 30,277
  • 10
  • 88
  • 118
  • 16
    While this answer compares two SDKs, it doesn't answers/explains which use when. It looks obvious that simpler way is the right choose to go with, but why the more complex option exists? Are there scenarios when it's better than the simpler one? – Kamarey Feb 19 '20 at 09:48
  • 1
    When we export DDB table into s3, that Json include data types like first code example. so we don't want to convert that ddb json format into the natural json format. we can use directly dynamodb (not dynamodb client) to use that json format. – Thiwanka Wickramage Jun 13 '21 at 15:41
21

As per the announcement of the DocumentClient:

The document client abstraction makes it easier to read and write data to Amazon DynamoDB with the AWS SDK for JavaScript. Now you can use native JavaScript objects without annotating them as AttributeValue types.

It's basically a simpler way of calling dynamoDB in the SDK and it also converts annotated response data to native JS types. Generally you should only use the regular DynamoDB client when doing more "special" operations on your database like creating tables etc. That's stuff usually outside of the CRUD-scope.

Shaho
  • 438
  • 3
  • 7
  • 10
    A concrete example is being able to indicate an attribute value like `':age': 21` with the DocumentClient whereas you have to indicate `':age': {'N': '21'}` with the regular client. Note that in the regular client case, you not only have to tell the client what type the attribute is ('N' for number), but you also have to indicate the value itself (21) as a string, even though it is a numeric value. – jarmod Sep 05 '19 at 13:17
  • Thanks for the answer. – Thiwanka Wickramage Sep 06 '19 at 03:39
  • Can you just use a normal javascript object as table input without the : in each field name? That would be ideal. – Andy N Dec 27 '21 at 06:50
4

In simpler words, DocumentClient is nothing, but wrapper around DynamoDB client. As per mentioned in other comments and aws documentation below, it features convenience of use, converting annotated response data to native JS types and abstracting away the notion of attribute values.

Another noticeable difference is that the scope of documentclient is limited to item level operations, but dynamodb client provides broader range of operations in addition to the item level operations.

From AWS document client documentation

The document client simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values. This abstraction annotates native JavaScript types supplied as input parameters, as well as converts annotated response data to native JavaScript types.

Shaggy
  • 484
  • 1
  • 6
  • 16