Model

Create Model From Schema

var Dog = dynamoose.model('Dog', dogSchema);

new Model(object)

Creates a new instance of the model. Object keys are assigned to the new model.

var odie = new Dog({
  ownerId: 4,
  name: 'Odie',
  breed: 'Beagle',
  color: ['Tan'],
  cartoon: true
});

model.put(options, callback) & model.save(options, callback)

Puts the item in the DynamoDB table. Will overwrite the item.

odie.save(function (err) {
  if(err) { return console.log(err); }
  console.log('Ta-da!');
});

odie.save({
    condition: '#o = :ownerId',
    conditionNames: { o: 'ownerId' },
    conditionValues: { ownerId: 4 }
  }, function (err) {
  if(err) { return console.log(err); }
  console.log('Ta-da!');
});

Options:

Model.batchPut(items, options, callback)

Puts multiple items in the table. Will overwrite existing items.

Dog.batchPut([
  {
    ownerId: 2,
    name: 'Princes',
    breed: 'Jack Russell Terrier',
    color: ['White', 'Brown'],
    cartoon: true
  },
  {
    ownerId: 3,
    name: 'Toto',
    breed: 'Terrier',
    color: ['Brown'],
    cartoon: false
  },
  {
    ownerId: 4,
    name: 'Odie',
    breed: 'Beagle',
    color: ['Tan'],
    cartoon: true
  },
  {
    ownerId: 5,
    name: 'Lassie',
    breed: 'Beagle',
    color: ['Tan'],
    cartoon: false
  }], function (err, dogs) {
    if (err) { return console.log(err); }
    console.log('Ta-da!');
  });

Options

overwrite: boolean

Overwrite existing item. Defaults to true.

updateExpires: boolean

Update the expires timestamp if exists. Defaults to false.

updateTimestamps: boolean

Should update the updatedAt timestamp if exists. Defaults to false.

condition: string

An expression for a conditional update. See the AWS documentation for more information about condition expressions.

conditionNames: object

A map of name substitutions for the condition expression.

conditionValues: object

A map of values for the condition expression. Note that in order for automatic object conversion to work, the keys in this object must match schema attribute names.

Model.create(object, options, callback)

Creates a new instance of the model and save the item in the table.

Dog.create({
  ownerId: 4,
  name: 'Odie',
  breed: 'Beagle',
  color: ['Tan'],
  cartoon: true
}, function(err, odie) {
  if(err) { return console.log(err); }
  console.log('Odie is a ' + odie.breed);
});

Model.get(key, options, callback)

Gets an item from the table.

Dog.get({ownerId: 4, name: 'Odie'}, function(err, odie) {
  if(err) { return console.log(err); }
  console.log('Odie is a ' + odie.breed);
});

Model.populate(options)

Populates paths from an item from the table.

(Only promise mode yet)

Dog = dynamoose.model('Dog', {
    id: {
      type:  Number
    },
    name: {
      type: String
    },
    parent: Number
  })

/*
Available dogs
{ id: 1, name: 'Odie'}
{ id: 2, name: 'Rex', parent: 1 }
{ id: 3, name: 'Fox', parent: 2 }
*/

Dog.get(3)
  .then(function(dog) {
    return dog.populate({
      path: 'parent',
      model: 'Dog',
      populate: {
        path: 'parent',
        model: 'Dog'
      }
    });
  })
  .then(function(dog) {
    console.log(dog);
    /*
    {
      id: 3,
      name: 'Fox',
      parent: {
        id: 2,
        name: 'Rex',
        parent: {
          id: 1,
          name: 'Odie'
        }
      }
    }
    */
  });

Populate with range and hash key

If the object to populate has both a range and hash key, you must store both in the attribute.

const CatWithOwner = dynamoose.model('CatWithOwner',
  {
    id: {
      type:  Number
    },
    name: {
      type: String
    },
    owner: {
      name: String,
      address: String
    }
  }
);

const Owner = dynamoose.model('Owner',
  {
    name: {
      type: String,
      hashKey: true
    },
    address: {
      type: String,
      rangeKey: true
    },
    phoneNumber: String
  }
);

var owner = new Owner({
  name: 'Owner',
  address: '123 A Street',
  phoneNumber: '2345551212'
});

var kittenWithOwner = new CatWithOwner({
  id: 100,
  name: 'Owned',
  owner: {
    name: owner.name,
    address: owner.address
  }
});

CatWithOwner.get(100)
.then(function(cat) {
  should.not.exist(cat.owner.phoneNumber);
  return cat.populate({
    path: 'owner',
    model: 'Owner'
  });
})
.then(function(catWithOwnerPopulated) {
  ...
});

Model.batchGet(keys, options, callback)

Gets multiple items from the table.

Dog.batchGet([{ownerId: 4, name: 'Odie'}, {ownerId: 5, name: 'Lassie'}], function (err, dogs) {
  if (err) { return console.log(err); }
  console.log('Retrieved two dogs: ' + dogs);
});

Model.delete(key, [options, ]callback)

Deletes an item from the table.

Dog.delete({ownerId: 4, name: 'Odie'}, function(err) {
  if(err) { return console.log(err); }
  console.log('Bye bye Odie');
});

options parameters:

model.delete([options, ]callback)

Deletes the item from the table. The options parameter is optional, and should be a object type if passed in. The callback parameter is the function that will be called once the item has been deleted from the table. The error and item (if update is set to true) will be passed in as parameters to the callback function. The options object accepts the same parameters as described above in Model.delete.

odie.delete(function(err) {
  if(err) { return console.log(err); }
  console.log('Bye bye Odie');
});

model.originalItem()

This function returns the last item that was saved/received from DynamoDB. This can be useful to view the changes made since the last DynamoDB save/received that your application made for a given document. This function will return a JSON object that represents the original item.

odie.originalItem(); // {ownerId: 4, name: 'Odie'}

Model.batchDelete(keys, options, callback)

Deletes multiple items from the table.

Dog.batchDelete([
  { ownerId: 2, name: 'Princes' },
  { ownerId: 3, name: 'Toto' },
  { ownerId: 4, name: 'Odie' },
  { ownerId: 5, name: 'Lassie'}
], function (err) {
  if (err) { return console.log(err); }
  console.log('Bye bye my friends');
});

Model.update(key, update, options, callback)

Model.update(keyWithUpdate, callback)

Updates and existing item in the table. Three types of updates: $PUT, $ADD, and $DELETE.

The key can either be its own object or combined with the update object.

$PUT

Put is the default behavior. The three example below are identical.

key and updated are separate

Dog.update({ownerId: 4, name: 'Odie'}, {age: 1}, function (err) {
  if(err) { return console.log(err); }
  console.log('Just a puppy');
})

key and updated are combined

Dog.update({ownerId: 4, name: 'Odie', age: 1}, function (err) {
  if(err) { return console.log(err); }
  console.log('Just a puppy');
})
Dog.update({ownerId: 4, name: 'Odie'}, {$PUT: {age: 1}}, function (err) {
  if(err) { return console.log(err); }
  console.log('Just a puppy');
})

$ADD

Adds one or more attributes to the item. These attributes must be of the number or set type. If the attribute already exists it will be manipulated instead. If it’s a number the provided value will be added mathematically to the existing value. If the attribute is a set the provided value is appended to the set.

Dog.update({ownerId: 4, name: 'Odie'}, {$ADD: {age: 1}}, function (err) {
  if(err) { return console.log(err); }
  console.log('Birthday boy is one year older');
})

$DELETE

Removes one or more attributes from an item.

Dog.update({ownerId: 4, name: 'Odie'}, {$DELETE: {age: null}}, function (err) {
  if(err) { return console.log(err); }
  console.log('Too old to keep count');
})

Options

allowEmptyArray: boolean

If true, the attribute can be updated to an empty array. If false, empty arrays will remove the attribute. Defaults to false.

createRequired: boolean

If true, required attributes will be filled with their default values on update (regardless of you specifying them for the update). Defaults to false.

updateTimestamps: boolean

If true, the timestamps attributes will be updated. Will not do anything if timestamps attribute were not specified. Defaults to true.

updateExpires: boolean

If true, the expires attributes will be updated. Will not do anything if expires attribute were not specified. Defaults to false.

condition: string

An expression for a conditional update. See the AWS documentation for more information about condition expressions.

conditionNames: object

A map of name substitutions for the condition expression.

conditionValues: object

A map of values for the condition expression. Note that in order for automatic object conversion to work, the keys in this object must match schema attribute names.

returnValues: string

From the AWS documentation Use ReturnValues if you want to get the item attributes as they appear before or after they are updated. For UpdateItem, the valid values are:

Model.getTableReq()

The function will return the object used to create the table with AWS. You can use this to create the table manually, for things like the Serverless deployment toolkit, or just to peak behind the scenes and see what Dynamoose is doing to create the table.

Dog.getTableReq();
//  {
//    AttributeDefinitions: attrDefs,
//    TableName: name,
//    KeySchema: keySchema,
//    ProvisionedThroughput: provThroughput
//  }