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.

Name	Description	Type	Default
create	If 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.	Boolean	true
throughput	An 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.read	What the read throughput should be set to. Only valid if throughput is an object.	Number	1
throughput.write	What the write throughput should be set to. Only valid if throughput is an object.	Number	1
prefix	A string that should be pre-pended to the table name.	String
suffix	A string that should be appended to the table name.	String
waitForActive	Settings 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.enabled	If Dynamoose should wait for the table to be active before running actions on it.	Boolean	true
waitForActive.check	Settings for how Dynamoose should check if the table is active	Object
waitForActive.check.timeout	How many milliseconds before Dynamoose should timeout and stop checking if the table is active.	Number	180000
waitForActive.check.frequency	How 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.	Number	1000
update	If 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
expires	The 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 | Object	undefined
expires.ttl	The default amount of time the item should stay alive from creation time in milliseconds.	Number	undefined
expires.attribute	The attribute name for where the item time to live attribute.	String	ttl
expires.items	The options for items with ttl.	Object	{}
expires.items.returnExpired	If Dynamoose should include expired items when returning retrieved items.	Boolean	true
tags	An object containing key value pairs that should be added to the table as tags.	Object	{}
tableClass	A string representing the table class to use.	"standard" | "infrequentAccess"	"standard"
initialize	If Dynamoose should run it's initialization flow (creating the table, updating the throughput, etc) automatically.	Boolean	true

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.

Name	Description	Type	Default
return	What 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 | undefined	undefined

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");
    }
});

table.query([callback])

You can query the table to get all the relevant items.

Useful for utilising the single-table approach when you store items of multiple models within same single table, and you want to get all the items, for example, with common primary key:

const Team = dynamoose.model("Team", {
  "pk": {
    "type": String,
    "index": {
      "hashKey": true,
      "index": {
        "name": "primary",
        "type": "global"
      }
    },
    "map": "id"
  },
  "sk": {
    "type": String,
    "rangeKey": true
  },
  "name": String,
  "type": {"type": String, "default": "team"}
});
const TeamMember = dynamoose.model("TeamMember", {
  "pk": {
    "type": String,
    "index": {
      "hashKey": true,
      "index": {
        "name": "primary",
        "type": "global"
      }
    },
    "map": "teamId"
  },
  "sk": {
    "type": String,
    "rangeKey": true,
    "map": "id"
  },
  "name": String,
  "type": {"type": String, "default": "member"}
});
const table = new dynamoose.Table("teams", [Team, TeamMember]);

const team1 = new Team({"id": "team_1", "name": "Team 1"});
const member1 = new TeamMember({"teamId": "team_1", "id": "member_1", "name": "Team member 1"});

await table.query({"pk": "team_1"}).exec()
// will return the following:
[
  Team {
    id: 'team_1',
    sk: '',
    name: 'Team 1',
    type: 'team'
  },
  TeamMember {
    teamId: 'team_1',
    id: 'member_1',
    name: 'Team member 1',
    type: 'member'
  },
]

Query execution result is all the relevant items with its correct models (Team and TeamMember)