Skip to main content

Table

The Table object represents a single table in DynamoDB. It takes in both a name and array of models and has methods to retrieve, and save items in the database.

new dynamoose.Table(name, models[, options])

This method is the basic entry point for creating a table in Dynamoose.

The name parameter is a string representing the table name. Prefixes and suffixes may be added to this name using the config options.

The models parameter is an array of Model instances.

const dynamoose = require("dynamoose");

const Order = dynamoose.model("Order", {"id": String});
const Shipment = dynamoose.model("Shipment", {"id": String});
const Table = new dynamoose.Table("Table", [Order, Shipment]);

The options parameter is an optional object used to customize settings for the table.

NameDescriptionTypeDefault
createIf Dynamoose should attempt to create the table on DynamoDB. This function will run a describeTable call first to ensure the table doesn't already exist. For production environments we recommend setting this value to false.Booleantrue
throughputAn object with settings for what the throughput for the table should be on creation, or a number which will use the same throughput for both read and write. If this is set to ON_DEMAND the table will use the PAY_PER_REQUEST billing mode. If the table is not created by Dynamoose, this object has no effect.Object | Number | String
throughput.readWhat the read throughput should be set to. Only valid if throughput is an object.Number1
throughput.writeWhat the write throughput should be set to. Only valid if throughput is an object.Number1
prefixA string that should be pre-pended to the table name.String
suffixA string that should be appended to the table name.String
waitForActiveSettings for how DynamoDB should handle waiting for the table to be active before enabling actions to be run on the table. This property can also be set to false to easily disable the behavior of waiting for the table to be active. For production environments we recommend setting this value to false.Object
waitForActive.enabledIf Dynamoose should wait for the table to be active before running actions on it.Booleantrue
waitForActive.checkSettings for how Dynamoose should check if the table is activeObject
waitForActive.check.timeoutHow many milliseconds before Dynamoose should timeout and stop checking if the table is active.Number180000
waitForActive.check.frequencyHow many milliseconds Dynamoose should delay between checks to see if the table is active. If this number is set to 0 it will use setImmediate() to run the check again.Number1000
updateIf Dynamoose should update the capacity of the existing table to match the model throughput. If this is a boolean of true all update actions will be run. If this is an array of strings, only the actions in the array will be run. The array of strings can include the following settings to update, ttl, indexes, throughput, tags, tableClass.Boolean | [String]false
expiresThe setting to describe the time to live for items created. If you pass in a number it will be used for the expires.ttl setting, with default values for everything else. If this is undefined, no time to live will be active on the model.Number | Objectundefined
expires.ttlThe default amount of time the item should stay alive from creation time in milliseconds.Numberundefined
expires.attributeThe attribute name for where the item time to live attribute.Stringttl
expires.itemsThe options for items with ttl.Object{}
expires.items.returnExpiredIf Dynamoose should include expired items when returning retrieved items.Booleantrue
tagsAn object containing key value pairs that should be added to the table as tags.Object{}
tableClassA string representing the table class to use."standard" | "infrequentAccess""standard"
initializeIf Dynamoose should run it's initialization flow (creating the table, updating the throughput, etc) automatically.Booleantrue

The default object is listed below.

{
"create": true,
"throughput": {
"read": 5,
"write": 5
}, // Same as `"throughput": 5`
"prefix": "",
"suffix": "",
"waitForActive": {
"enabled": true,
"check": {
"timeout": 180000,
"frequency": 1000
}
},
"update": false,
"expires": null,
"tags": {},
"tableClass": "standard",
"initialize": true
}

dynamoose.Table.defaults.get()

This function is used to get the custom default values that you set with [dynamoose.Table.defaults.set(defaults)].

console.log(dynamoose.Table.defaults.get());

dynamoose.Table.defaults.set(defaults)

This function is used to set default values for the config object for new tables that are created. Ensure that you set this before initializing your tables to ensure the defaults are applied to your tables.

The priority of how the configuration gets set for new tables is:

  • Configuration object passed into table creation
  • Custom defaults provided by dynamoose.Tables.defaults.set(defaults)
  • Dynamoose internal defaults

In the event that properties are not passed into the configuration object or custom defaults, the Dynamoose internal defaults will be used.

You can set the defaults by setting the property to a custom object:

dynamoose.Table.defaults.set({
"prefix": "MyApplication_"
});

In order to revert to the default and remove custom defaults you can set it to an empty object:

dynamoose.Table.defaults.set({});

table.name

This property is a string that represents the table name. The result will include all prefixes and suffixes.

This property is unable to be set.

const DynamoTable = new dynamoose.Table("Table", [Model]);

console.log(DynamoTable.name); // Table
const DynamoTable = new dynamoose.Table("Table", [Model], {"prefix": "MyApp_"});

console.log(DynamoTable.name); // MyApp_Table

table.hashKey

This property is a string that represents the table's hashKey.

This property is unable to be set.

const DynamoTable = new dynamoose.Table("Table", [Model]);

console.log(DynamoTable.hashKey); // id

table.rangeKey

This property is a string that represents the table's rangeKey. It is possible this value will be undefined if your table doesn't have a range key.

This property is unable to be set.

const DynamoTable = new dynamoose.Table("Table", [Model]);

console.log(DynamoTable.rangeKey); // data

table.create([config][, callback])

This method can be used to manually create the given table. You can also pass a function into the callback parameter to have it be used in a callback format as opposed to a promise format.

The config parameter is an optional object used to customize settings for the model.

NameDescriptionTypeDefault
returnWhat Dynamoose should return. Either a string request, or undefined. If request is passed in, the request object will be returned and no request will be made to DynamoDB. If undefined is passed in, the request will be sent to DynamoDB and the table will attempt to be created.String | undefinedundefined
const DynamoTable = new dynamoose.Table("Table", [Model]);

try {
await DynamoTable.create();
} catch (error) {
console.error(error);
}

// OR

DynamoTable.create((error) => {
if (error) {
console.error(error);
} else {
console.log("Successfully created table");
}
});
const DynamoTable = new dynamoose.Table("Table", [Model]);

try {
const request = await DynamoTable.create({"return": "request"});
console.log("DynamoTable create request object:", request);
} catch (error) {
console.error(error);
}

// OR

DynamoTable.create({"return": "request"}, (error, request) => {
if (error) {
console.error(error);
} else {
console.log("DynamoTable create request object:", request);
}
});

table.initialize([callback])

This method will run Dynamoose's initialization flow. The actions run will be based on your tables options at initialization.

  • create
  • waitForActive
  • update
const DynamoTable = new dynamoose.Table("Table", [Model], {"initialize": false});
await DynamoTable.initialize();
const DynamoTable = new dynamoose.Table("Table", [Model], {"initialize": false});
DynamoTable.initialize((error) => {
if (error) {
console.error(error);
} else {
console.log("Successfully initialized table");
}
});